BootROM
Engineering Requirements Specification
(ERS)

Date	Author	Comments
14 Feb 2000	Dennis Ruffer	Clean up outline format in Microsoft Word and add Table of Contents
24-June-1999	Ben Koning	Flesh out OF Kernel init; needs more. Add some debugging how-to's.
23-June-1999	Ben Koning	Rudametary OF kernel init description and handoff to pure-OF code.
18-June-1999	Ben Koning	OF compile description. OF runtime description. Yosemite-specific exhaustive file delta list.
11-June-1999	Ben Koning	Hardware Init description. Memory map. ROM layout map. Copied new System Configuration block information provided by John Hall.
2-June-1999	Ben Koning	Console output. More doc reorg. Assigned-Addresses. NVRAM correction.
26-May-1999	Ben Koning	More file system syntax and file system info. Section about booting. Reorganize document away from ERS template toward 3 sections: process, specific, general.
18-May-1999	Ben Koning	Finish the NVRAM section.
14-May-1999	Ben Koning	Add revision history. To-do: add NVRAM format, add full Multiboot+BPS discussion at user level for testers; add HWInit discussion, add Yos memory map; add stuff in all things only in outline form; organize and properly decimalize this entire document proofread for errors; proofread for spelling; proofread for style.
3-May-1999	Ben Koning	First checked in to `{BR}` project. Based on ANPP ERS template.

Document Organization

This document used to follow the ANPP ERS but was instead organized into 3 sections: Process, Specific, and General.

The Process section (section P) describes everything of process importance that is more pedestrian than engineering yet still a prerequisite for engineering. Personnel, server locations, code names, project schedule history, bug review process, feature inclusion/exclusion management, edit-compile-test development cycle and more make up this section. Anything that is required for engineering but not the engineering itself is included.
The Specific section (section S) describes everything of engineering importance to the implementation of the BootROM for this machine as opposed to any other machine, especially such things as specific settings for and structures of such things as NVRAM defaults, aliases, slot names, the device tree/bus structure, and more.
The General section (section G) describes common features of the BootROM and its interaction with the OS. Also, items that are potentially of general use or application are described in this section even though they may be new to the specific machine and not yet in use by anyone else.

Even with this organization, there will be some exceptions: For example, the General section may use machine-specific examples, etc.

The exact numbering scheme of the ANPP ERS was discarded, but its Table of Contents section headers all exist in this document, scattered throughout using a different numbering scheme; if no information exists under than header it nevertheless still exists.

Disclaimer

This Document May Contain Errors -- Beyond a certain point, the author had to research much of the information presented herein by examining source code and trying experiments on a target machine. This document has not yet been reviewed as of its initial release date (25-June-1999), and thus may contain factual and organizational errors. Wherever something is known or suspected to be questionable, the text is tagged with "???".

In particular, as of this writing the format of the Boot Config Block was just about to change slightly.

PROCESS

Machine-Specific BootROM Organizational Information

Organizational Project Info

Code Names and BBS Targets

Yosemite Products

Code Name	Shipping Name	Release Date	BBS Target	Description
Half Dome	Power Macintosh G3 (blue/white enclosure)	None	None	First try at Yosemite using Groupe Bull instead of Motorola MPC106 ("Grackle") memory controller.
Yosemite	Power Macintosh G3 (blue/white enclosure)	January 8, 1999 (MacWorld)	Team=BootROM, Build=Yosemite,VersionSet=`Yosemite_10f5`, VersionSet=`Yosemite_GM`, VersionSet=`Yosemite_ForkThis,159` (all identical)	MacWorld shipping version; contains PCI throughput bugs.
Yosemite Quick Turn	Power Macintosh G3 (blue/white enclosure)	Circa May 1999	Team=BootROM, Build=Yosemite, VersionSet=`Yosemite_BootROM_1.1f4`	Factory roll-in and web-downloadable updater; fixes throughput and other bugs.
Yosemite Speed Bump	Power Macintosh G3 (blue/white enclosure)	TBD	Team=BootROM, Build=Yosemite, VersionSet=`Yosemite_BootROM_1.2`xxx	Factory roll-in along with faster CPU module and jumper block.

In general, the version set "Yosemite_ForkThis" is used to keep Yosemite builds more stable and away from Top-Of-Trunk and is thus a precursor to more rigid release-based version sets, such as "Yosemite_BootROM_1.1f4". The version set "Yosemite_ForkThis" changes over time, whereas release-based version sets do not, except perhaps in the rare case of a pre-SCM build mistake.

P.1.2. Milestones

P.1.2.1. Early History

The Yosemite project started as the "Half Dome" project. Instead of using a Grackle (Motorola MPC 106) memory controller / PCI controller, a chipset from Groupe Bull, an Italian workstation / server vendor, was to be used. This did not happen. At the time of the switch to the MPC 106, the date was around February 1998.

P.1.2.2. MacWorld GM

BBS Version Set for GM: Yosemite_ForkThis,159 or Yosemite_BootROM_GM.

Yosemite was introduced at the January 1999 MacWorld in San Francisco. The last checkin of substance (other than mod date change) was the evening of 8-December-1998.

P.1.2.3. Quick Turn

BBS Version Set for ongoing "Quick" Turn development: Yosemite_ForkThis.

Soon after Yosemite was introduced at MacWorld it became apparent that a number of hardware and software bugs existed which were quite serious and should have been caught. Fortunately, the BootROM is flashable, and so work was started on a "Quick Turn" ROM update that customers could download or dealers could install; plans were for the factory to silently roll the change in. As of this writing (3-May-1999) this most likely has occurred with version 1.1f4.

Major Bugs (Reasons for the Quick Turn) And Solutions

Some of these are straight software bug fixes; some are software workarounds for hardware problems; some are stop-gap software measures in liu of a more proper software solution.

Opportunistic Inclusions in the Quick Turn

The following software fixes or feature enhancements were judged compelling and safe enough for inclusion. These changes were actually slated either for other projects of for future Yosemite endeavors such as the Speed Bump.

P.1.2.4. Speed Bump

BBS Version Set for ongoing Speed Bump development: Yosemite_Future.

A speed bump revision of the BootROM is still planned at this time (3-May-1999) to support 450MHz and faster processors. Other than opportunistic bug fix inclusions, the main changes should be minimal and limited to Hardware Init.

P.1.3. Personnel

The following list of names are of some of those who were intimately involved in the Boot ROM software for Yosemite. It does not attempt to be complete, nor does it cover hardware, nor does it cover anything but BootROM software. Even for the only part of the total project that the Boot ROM is, there are many, many other people who contributed code, found bugs, etc. The "group" category is not necessarily reflective of actual group names; it is for archtectural overview reference only.

Yosemite Software Personnel (Selected)

Name	Group	Description
Bob Bradley	Project:SW	Yosemite project Hardware Init / POST
Stuart Russell	Project:SW	Yosemite project Enabler / MacOS integrator
Ben Koning	OF	Yosemite project Open Firmware / Boot Search: low-level
Ron Hochsprung	DEST	All projects Open Firmware architect and mega-contributor
Michael Larson	Project:SW	Manager, Yosemite project software
Dave Carlton	OF	Manager, Open Firmware / BootROM
Jim Huffman	OF	Boot Search: high-level, boot GUI
Dave Radcliffe	MacOS	Boot Search: MacOS control panel, MacOS boot-time adaptation
Matt Denman	MacOS	Installers
Josh DeCesare	MacOS-X	Ensure that OF boots MacOS-X as well as conventional MacOS
Mitch Orysh	Project:HW	Hardware integrator
Keith Yarak	Project:HW	Hardware
Norman Leung	Mass Storage	Contact for command set specs for specific ATA, ATAPI, SCSI, etc, devices

P.1.3.1. Personnel organization

Usually the engineering division of labor follows both functional (people with specialties in specific areas) and project (people working on a specific machine) alignments simultaneously. Core project hardware and software groups are usually formed around a specific new machine project. The engineers in these groups function as integrators and also creators of very machine-specific components. Engineers in other groups provide the machine-specific group with new components as needed or feature additions or bug fixes to existing components as needed for the new machine (they do not physically do such "provide"-ing; everyone in the company checks code in to the same source code control base).

The organization in the Open Firmware group, which handles everything in the BootROM except Hardware Init and 3rd party drivers, mirrors the larger organization described above. Everyone has or develops a specific subject-related specialty, and at any given time several people are also involved as tech leads on specific machine projects. Those that are on machine projects interface with those groups, and ask other members of the BootROM group to do tasks as necessary to balance the workload. In general, sooner-shipping projects have priority over later-shipping projects or non-project-specific work, if a tech lead needs another BootROM group member's help. Note that non-project-specific work here does not include such non-specific work that is needed by a machine project; quite often, general work may be needed by several upcoming machines.

In addition to the above, Ron Hochsprung does the work of about three very senior engineers and is also the architect, often defining new directions.

P.1.4. Development Provider

?????

P.2. Component Description

Second of the OF-3 architecture machines (iMac was the first). "OF-3" refers to a more robust implementation of Open Firmware

xxxxxxxxxxxxxxxxxxx

P.3. Dependencies

OF checks the beginning of the tbxi file for its list of supported machines. If no match, then control is returned to the load caller with an error. This is how a machine prevents itself from wasting time trying to boot versions of system software that are older than the machine.

??????this is descibed better elsewhere in the boot section, so get rid of this???????

The OF code (in text) at the beginning of the tbxi file then checks the "/" "compatible" property against a list that it has of machines that it wants itself to boot from. If it does not like what machine it is on, it exits, and thus control is returned to OF with a load error; OF will probably look for something else to boot. This is how system software prevents itself from running on machines that are too old, or for which it was not designed.

For example, iMac shipped before Yosemite. Both are OF-3, NewWorld machines. So what prevents a Yosemite CD from erroneously booting an iMac? The second mechanism described above. Later MacOS CDs, on the other hand, might be designed to boot both iMac and Yosemite (and others).

P.4. Outside Interface

P.4.1. User Experience

?????? gray screens, boot feeback, bootrom flash

P.4.2. Programmer Feature Set

the bytecode described in ieee1275 and firworks doc; the user interface shell

P.4.3. Compilation Interfaces

???????

P.4.4. Data Structures and File Formats

P.4.4.1. File Formats, Types, and Creators

table goes here

File Type	File Creator	Usual Name	Description
tbxi	chrp
tbxj	chrp
.fmwr / .fw	chrp
fw99

P.4.4.2. Yosemite.ofz

Yosemite.fmwr

The ".fmwr" file is just like the ".ofz" file, with the exception that it automatically performs a flash and reboot. It is intended for use with a MacOS application-level installer for users to use; the installer writes the .fmwr file to the boot disk and sets it to be the boot program; after flash and reboot the installer recognizes the fact that the .fmwr file ran and removes it.

BootROMYosemite

-describe what all of these are, ie, incl .fmwr file

P.4.4.3. yes data structures are exposed

P.4.4.4. yes file formats are publicly exposed

P.4.4.4.1. CHRP boot file secondary loader format

P.5. Key Algorithms

P.5.1. Critical Sections and Synchronization

Open Firmware is fully single-threaded, with as the only exception the PowerPC CPU decrementer interrupt used to drive "alarm" tasks, which are much like MacOS VBL or Time Manager tasks. Device drivers in particular need not be multi-threaded or asynchronous, they can and should block until I/O is complete, and can use either programmed I/O or DMA as they see fit.

Like such MacOS tasks, which run at "interrupt time", OF alarm tasks must be careful not to do damage to code "running in the foreground". Unlike MacOS, memory allocation from inside an alarm task should be OK; the code in ALLOC-MEM.of seems surround critical data structure modification sections with disable/restore of alarm tasks. Still, one must be careful. Note that code in "do-quiesce" turns off alarms, among other things; there are also various time and/or data structure-critical sections such as hand-programmed serial I/O to microcontrollers (PMU, CUDA) that turn off alarms.

P.6. Compatibility Issues

P.6.1. Generic Names

talk about / see section about generic names

P.7. Internationalization

No overt internationalization issues exist; the OF user interface shell is Roman/English only. It is conceivable that alternate-language mnemonics and a programmer's manual could be made for the FCODE bytecodes.

P.7.1. Worldwide Boot Search Issues

The Multiboot OS Picker and Mac-Boot Boot Searcher carry a few internationalizion issues; the Mac-Boot "snag" keys are Roman/English-based (ie, "D" for "disk") but it is kind of a standard. Likewise, the OS Picker may display bus names such as "SCSI" or "ATA" in Roman/English, but again, these are standards in any language.

Perhaps the most serious problem is that of how to display the volume names of bootable entities in the OS Picker; OF is far not sophisticated enough to display non-Roman glyphs. A currently working proposed solution is to have MacOS save a file with a graphics image of the name for OF to display.

P.8. Qualification Methodology

xxxxxxx

P.8.1. Performance Characteristics and Measurement Methodology

xxxxxxx

P.8.2. Fault Handling Methodology and Mechanisms

xxxxxxx

P.8.3. Experimental Justification

xxxxxxx

P.8.4. Integration Strategy

xxxxxxx

P.9. Software Configuration and Code Management

Apple system software process pertaining to BootROM

As mentioned elsewhere, the BBS web site contains information on how to get started, contains full information, and is the final source process authority.

P.9.1. Source Base

The standard Apple System Software Source Code BBS servers are used; see http://web.apple.com/areas/eng/bbs.

P.9.2. Tool Requirements

Standard MPW tools as required by BBS; at this time (3-May-1999), this is MPW 3.4.3. BBS is a collection of MPW scripts which aids in source control and compiling of Apple System Software projects. BBS software and information, with links to software such as MPW, getting-started-guides, and its electronic server account request facility, are available at http://web.apple.com/areas/eng/bbs.

Some of the specialized MPW Shell tools used in the BootROM build process, such as layoutimage, checksum, lzss, etc, are created and maintained by the BootROM team, are built only when they change, have their executables checked in to {BootROM}:Tools and have their sources checked in to {BootROM}:Tools:ToolSource.

P.9.2.1. Languages

The C, PowerPC Assembly, and Forth languages are used. The BBS project team entity "ForthCompiler" is used to generate the MPW tool "AForth", which is based on a public domain version of Forth written in C named "ThisForth". See "Build Strategy" below for more information on how the Forth sections of the BootROM are built; it is not straightforward.

P.9.2.2. AForth Tool

xxxxxxxxxxx do we want to describe how this thing is built, or just a quick summary of what it is?

P.9.2.3. LayoutImage Tool

layoutimage [options] section [section…] > map

-ofile # specify output file (default Image.out)

-ssize # desired size of output file

-d# generate a directory

-m# write map file (listing locations/sizes) to <stdout>

-4 MMmmssrr# create a 4MB "classic" Mac ROM where:

MM = ROM major version

mm = ROM minor version

ss = ROM sub-version

rr = ROM revision

Note: A "section" has one of these forms:

-bfilename

-xfilename

-rfilename,TYPE=ID

-pdummy

-b# read file as binary -- data fork only

-x# read file as XCOFF -- text / data loaded only

-r# read resource TYPE=ID from the resource fork

-p# padding -- create an empty directory entry

P.9.3. Process

P.9.3.1. Checkin Email

Whenever a change is made to BootROM source code, the engineer should send a message to the email group address BootROM@group.apple.com. See the BBS web site to subscribe/unsubscribe (do not email "subscribe" or "unsubscribe" to the group address). The email should list the files changed and the reason for the change. In particular, it is important to write good subject lines that start with "BR-" (for "BootROM") so that they can be discriminated in people's email in-boxes (in fact, many people have scripts that look for such prefixes). If a change affects a software interaction with the OS (see x.x.x, xxxxxxxxxxx) , then the message should also be sent to NewWorld@group.apple.com or blue-list@group.apple.com.

P.9.3.2. Version Sets

xxxxxx

P.9.3.3. Embedded Versions in the Image

As per standard Apple guidelines: When a project is first in development, and there is no hardware yet, the software-only effort is usually given version numbers

scm and project stuff and don't we have the bbs stuff elsewhere? most symbols names are of the form xxxx-xxx; dashes are used a lot; capitals are used a lot

case-insensitive for symbols, but compile-time and run-time call-method-by-name

special characters can be part of idenitfies, so ie you can have l,

P.9.3.4. Standards, Building Codes, and Guidelines

xxxxxx

P.9.4. BootROM source code organization

directory structure (listed in no particular order) and explanation of what's inside

BootROM Source File Layout

This is an overview of directories only; for a more detailed file description see section G.4.1, "BootROM OF Image Compilation Process".

Directory / Project "Directory"	Contents
`BootROMSources`	This BBS-generated directory shows what BBS project entity the directory's contents came from by its name, and inside is a file that translates between BBS-checkin-comment initials and full author names. Suggestion: In the same spirit it can be useful to manually put a folder name here that indicates what version set one currently has updated to; perhaps BBS should do this.
`VersionSets`	A collection of files, each called a "Version Set", and created by BBS menu scripts, that lists a collection of BootROM source files and all of their revision numbers. Can be used to symbolically name a snapshot in time of current sources state. Most version set files, such as those that refer to a specific "build", are never updated and thus have only one version; some version set files, however, are updated regularly and thus the version set file itself has many revisions.
`Documentation`	Any technical documentation related to the BootROM goes here.
`BuildResults`	All results of compilation goes here; this includes statistics such as symbol tables also.
`Tools`	Tools from the Tools directory below which are built while developing them are put here; when working, their executables are checked-in to the Tools directory below.
`Obj`	Intermediate-build products go here.
`Yosemite`	Each BBS build sub-target (usually corresponding to a machine) has its own build results subdirectory to avoid collisions when often building for multiple machines.
`Obj`	Intermediate-build products go here.
`Text`	Statistics and debugging output goes here. In particular, the `Yosemite.log` file is of use when there is an OF compilation error.
`Make`	The BBS scripts look here for a `Build` script, which is where the build process starts, and this is how BBS knows what builds exist. Also in this directory are such things as the `DeleteObsolete` reaper, the `BuildOptions` list, and the initial makefiles that the `Build` script invokes.
`BuildSpecific`	This is a place to put machine-specific files related to the BootROM build process. For each machine, there is a specific makefile that is invoked by the master makefile in the `Make` directory. There is also a PPC assembly "`.s`" source file that functions much like OF sources' `Yosemite.fth` and `META-COMPILER.fth` in that it invokes the compilation of other files by including them (twice -- once for definitions, then again for code). OF build-specific sources are not here; they are instead in `OF:OFSources:Projects`; perhaps those sources should be brought here.
`Yosemite`	Each BBS build sub-target corresponding to a machine is located in its own directory.
`POST`	Boot Block (out of reset) and Hardware Init sources; depending on taste, for some projects these are "`.s`" files compiled by `PPCAsm` and sometimes they are "`.fas`" files compile by `aforth` and the FORTH assembler. It is called POST for Power On Self Test, which is only one of the actions performed (in `Diagnostics.s`).
`OF`	All of the OF sources go here.
`OFTools`	??? this is a leftover from the past; superseded by both the ForthCompiler BBS entity and the main Tools directory.
`OFSources`	All of the OF sources that are not build-time tools go here.
`Bus`	All OF code that has to do with basic motherboard bus architecture, such as directing the high level of PCI probe and Device Tree construction; therefore contains some sections of per-machine conditionally compiled code. Slot names and PCI hardware address assignments happen here.
`Common`	All OF code that is of a "shared library", "middleware", or "high-level" nature, such as mass storage common driver routines, buffering, partitioning interpretation, file systems, executable load format interpretation, BootPath-Search and Mac-Boot, user-interface terminal graphics, PCI probe abstract non-machine-specific help, etc.
`IO`	All OF code that has to do with input / output devices including mass storage device drivers, hot pluggable "buses" such as FireWire and USB, network device drivers, on-board I/O such as sound, etc.
`Kernel`	Basic OF low-level services that are needed once OF is up, such as a runtime model, memory allocation, memory access, etc. Also OF compilation (`META-COMPILER.fth`, `asmPowerPC.fth`, `META-TOKENIZER.fth`). Also the initial entry point and subsequent execution architecture (again `META-COMPILER.fth`, `KERNEL.fas`, `BYTE-LOADER.of`). Also the basic "OS" (`RESOLVE.of`, `USER-INTERFACE.of`, `ALLOC-MEM.of`, etc).
`Projects`	All OF project-specific changes go here. As much as possible is put here, but note that there is still a small amount of conditionally-compiled code elsewhere in the OF sources; whenever possible, such code should be moved here. For each machine, there is a main "`Yosemite.fth`" file that contains parameters for the build and invokes `META-COMPILER.fth`; this is like `BuildSpecific`'s `Yosemite.s`. Also, the very machine specific files `THE-TREE.of`, `THE-FILES.of`, and `FINISH-DEVICE-TREE.of` are located here.
`Yosemite`	Each BBS build sub-target corresponding to a machine is located in its own directory.
`RTAS`	Run Time Abstraction Services sources; a mix of OF and C source texts.
`Tools`	Any code compiled for running during compile of the BootROM should be in this directory. Executables should be checked-in at this level; their corresponding sources should be in a subdirectory.
`ToolLibs`	This is where stub libraries (very much like header files) should be.
`ToolSource`	This is where tool source code should be.
`OS`	Any code compiled for running under an operating-system (MacOS 8, MacOS 10, or other) which nevertheless resides here in the BootROM sources because it is closely related to such or is done by the BootROM team should be in this directory.
`iMacOpenPromMacOSPatch`	Not-finished MacOS Extension capable of inserting OF patches into OF-3 (partitioned) NVRAM; even the nondestructive "addition" of patches will be possible; this extension could service all machines or be targeted to only a single machine; works with pre-MacOS 8.7 where certain MacOS APIs were not readily available. It started to solve a very specific problem for certain iMac's, hence the name, but became unnecessary.
`MultiBootVolumeNamer`	Experimental MacOS Extension which "solves" the Multiboot OS Picker localizability problem by writing '`tbxj`'-typed files containing graphical images of volume names, thus overcoming the OF limitation of only being able to render Roman characters and the much less serious OF limitation of currently not being able to read volume names.

P.9.5. Feature Control and Bug Review Process

P.9.6. Any Details Not Described in the Design Document (kludges, work-arounds, etc.)

P.9.7. External Dependencies

P.9.7.1. Compile time

master intferfaces use?---do we use any, (not counting aforth)---what about hwinit

P.9.7.2. Link time

lib use? in any of the makefiles

P.9.7.3. Run time

From a stand-alone perspective, there are no software external run-time dependencies for the BootROM; other than embedded software (such as CUDA), the BootROM is the only piece of system software that can fully make this claim. The BootROM handles execution from the CPU's reset vector up until the handoff to the code inside the 'tbxi' file, usually called "Mac OS ROM".

However, there is an implied connection between PCI cards with expansion ROMs and the BootROM: Since the BootROM executes code on expansion ROMs (if found) and provides a rich API (FCODE), there is the danger of incompatiblities with existing cards. See the discussion of "generic names" in this document, for example.

There are specific runtime hardware dependencies: each BootROM, at least as of this writing (May 1999), is intended for a specific machine hardware platform. There has been discussion of a "universal" BootROM. In fact, it is the philosophy for the BootROM to, as much as possible, isolate system software from hardware dependencies, by means of Device Tree data, Multboot booting abstraction, and RTAS. In general, running a BootROM on the wrong machine will not even get that machine past the boot beep. If the machines are similar enough, however, it is worth noting for bring-up purposes that in the ".ofz" file takeover mode, a "wrong" BootROM or one with incomplete-Hardware-Init-brought-up-for-a-new-machine might work.

P.9.8. Build System and Environment

P.9.8.1. Development loop

The BootROM is built using either the standard BBS menu items or command lines, ie, "bbsbuild BootROM Yosemite". For a full build, try "bbsbuild -e BootROM Yosemite". Although a build of MasterInterfaces may be triggered, they are generally not needed by the BootROM and may even have compile errors yet still yield a "successful" build (for debugging, at least).

P.9.8.2. Build Results

Various output files are stored in the "BuildResults" directory, of which the following are used most often:

Yosemite.ofz is the BootROM image encapsulated inside an OF program that, after prompting the user, can program (update) the motherboard Flash ROM or run in take-over mode.
Yosemite.fmwr is like Yosemite.ofz but is automated for OS installers.
BootROMYosemite is the BootROM image bytes only for transmission to the factory or vendors or for use by certain OS flashers (flash ROM programmers).
Yosemite.log is the place to look for OF compile errors. BBS, Link, MPW, or PPCAsm errors will all be displayed to the MPW error output (the worksheet), but OF errors will not. However, OF errors do terminate the build (OF-2 did not do this in all cases).

After building, the BootROM can be run using the ".ofz" file's takeover feature or flash feature. While the takeover mode is convenient, flashing is highly recommended because rebooting provives a better test. Hardware Init does not run, and hardware is not in the same state as it would be from power up followed by Hardware Init.

P.9.8.3. Serial Output

If serial output is desired, a modem port to serial adapter card is required. This is called a "Jolly Roger" card; there is also a commercial product available from www.gee-three.com (the preceding is not an endorsement by Apple Computer, Inc.).

P.9.8.4. Recovery from broken BootROM (Flashback card)

If a motherboard BootROM is accidentally flashed with an image that does not at least boot the machine into the OF User Interface, then the only alternative to desoldering the on-board ROM is to use the "Flashback" card. The Flashback card installs into the RAM slot labelled J19 (the slot closest to the processor), and it has a jumper and LED: if the jumper is set one way, the LED illuminates and the card's ROM is active; if the jumper is set the other way, the LED is off and the motherboard's ROM is active; and the jumper can be changed while the power is on. Since only Hardware Init really runs out of ROM (OF is decompressed into RAM), you can boot from the ROM on the card, turn the card off, and run the ".ofz" file to update the motherboard. The card can be updated by running the ".ofz" file with the LED on.

P.9.9. Build Strategy

describe the horrendously complicated make->thisforth->aforth crap here

P.10. References

Most of the following references were used during BootROM development. Of all sources, the most important by far were Writing FCODE programs for PCI and a PCI bus software spec book (any one of several will suffice).

Name	Location	Description
Yosemite BootROM ERS	BootROM Sources `{BR}:Documentation`	This document
Writing FCODE programs for PCI	www.firmworks.com	Open Firmware API and tutorial; easier to use than IEEE 1275 spec
sssss
NewWorld Architecture	???????????????where is this document?????bbs web site?	Describes how MacOS currently boots with emphasis on what had to be changed to go from MacOS code and UniversalTables in ROM vs. MacOS code loaded into RAM by the Boot ROM and gathering data from Device Tree.
Radar	Components "Open Firmware", "Yosemite", "Yosemite BootROM"	Bug tracking database
Yosemite Server	`17.205.20.196`, or `IL5 2nd: HAL-2001 : HAL-Data : Yosemite` (13-May-1999; administrator = Sherri Patton, `sherri.p@apple.com`)	Yosemite-specific and -nonspecific hardware and software documentation, including devices, including many of the documents listed here
Yosemite Schematic	Yosemite Server, Mitch Orysh	Hardware information
Yosemite Hardware ERS	Yosemite Server, Mitch Orysh	Hardware information
Paddington ERS	Yosemite Server	Mac I/O Legacy ASIC data sheet (hardware and software)
USB documentation	Yosemite Server	There are two documents one should have: The OpenHCI (Host Controller Interface) spec, which defines the software interface, and then also the controller spec for the specific vendor's device.
ATA-3 documentation	Yosemite Server	ATA/IDE controller documents; actually there is not too much to it except the standard IDE register set.
ATA-4 (Ultra ATA) documentation	Yosemite Server	Additional features over ATA-3 such as 16-bit transfers.
ATA spec	Mass Storage Department. Examples: ATAPI DVD-ROM Command Set, Dwg Number: `062-3992`, contact Tricia Lozano or Carrie Holmes.	ATA-3/4 documentation only specifies how to talk to the device; device (vendor+model) -specific specs are required to know the command set and data structures. Most commands are the same across different vendors and models.
ATAPI spec	Mass Storage Department	See ATA spec.
FireWire documentation	Yosemite Server	Not much is done at OF level.
CUDA documentation	Yosemite Server	CUDA is a real-time-clock, power management, and ADB keyboard interface microcontroller. Not much is done at OF level; CUDA documentation shows the command set API to the chip (though communication has to be through a Paddington output bit).
Burgundy documentation	Yosemite Server	Sound ASIC ("codec").
PCI bus documentation	Various sources, including Yosemite Server, Mindshare Inc., etc	PCI config space registers, etc
IEEE 1275 Specification	`www.ieee.org`, `www.standards.ieee.org/catalog`	Open Firmware API
Starting FORTH	Leo Brodie, Starting FORTH, Prentice Hall, ISBN `0-13-843087-X`, `0-13-843079-9`	FORTH language tutorial; Open Firmware is implemented in FORTH and client (card expansion ROM firmware) execute a bytecode (called FCODE) based on FORTH with Open Firmware-specific API extensions.
PowerPC User's Manual	Motorola, book #`MPC750UM/AD`	CPU (software) data book
MPC106 User's Manual	Motorola, book #`MPC106UM/AD`	Memory controller (hardware and software) data book
Inside Macintosh	Various sources or `www.developer.apple.com` for an online version	MacOS API
BootPath-Search (BPS)	BootROM Sources `{BR}:Documentation`	Mid-level services for OS boot search.
Multi-Boot / OS Picker	`www.oftech.apple.com`	High-level OS boot search services; includes mimicked traditional StartSearch behavior as well as an OS Picker. The OS Picker is disabled on Yosemite.

P.11. Glossary

The list below highlights certain themes discussed in this document. It is not intended to be complete.

Term	Description
Open Firmware, OF	Open Firmware (IEEE 1275). Boot firmware that allows I/O cards to provide CPU- and OS- independent declaration and boot device driver services by means of bytecode token execution and the building of a Device Tree data structure prior to OS boot. Derived from Sun Microsystems' Open Boot.
OF-1	Apple's first implementation of OF; shipping on PowerMac 9500, etc. MacOS not very dependent on it; serial port console only; not in good enough shape to boot.
OF-2	Apple's second implementation; shipping on non-blue/white G3, etc. MacOS more dependent on it; serial port or video card console; almost good enough to boot (that is, device drivers, file system handling, etc, almost all working).
OF-3	Apple's third implementation; debut on iMac, shipping on blue/white G3. MacOS very dependent on it (having very much foregone the MacOS "universal tables" mechanism which is much like OF's Device Tree), especially for interrupt handling. Good enough to boot, and in fact, it is now the way the OS boots (see NewWorld architecture). Vast number of robustness bugs fixed (ie, memory leaks and other load-handling issues). Working OF debugger, boot search ("StartSearch") architecture, network booting, new NVRAM structure, OS ability thru NVRAM to add device tree properties (ie, for video card resolution settings), etc.
1275, IEEE 1275	See OF.
Open Firmware	See OF.
TBD	To be decided.
RTAS	Run Time Abstraction Services. These are machine-specific routines suc as NVRAM setting, clock setting, etc. They appear as a node in the device tree and can be activated via Client Interface calls. MacOS currently does not use RTAS very much and there is talk of removing it.
Client Interface (CI)	Programmatic services that OF supplies to non-OF programs. For example, a native machine code program (compiled from C source code, for example) that is loaded and executed by OF can make callbacks to OF to do console I/O, examine the Device Tree, etc. In fact, it is through this mechanism that an OS, such as some of the initialization code in the file "Mac OS ROM", downloads Device Tree contents and optionally outputs debugging text.
User Interface (UI)	Interactive shell for debugging. Can be activated by holding down CMD-OPT-O-F keys during and right after boot beep; can also be activated by typing `"setenv auto-boot? false"` (CMD-OPT-P-R or setting `auto-boot?` back to `true` sets things back to normal). Can use the console (ie, locally-connected keyboard and screen) or serial port (ie, for capture, download, cut/paste, convenience, or video card or keyboard debugging): try "`scca io`" with a 57600/8N/1 terminal connection.
MacOS-X	UNIX-based MacOS; think of it as "Mac OS NT".
Rhapsody	Older code name for MacOS-X.
Take-Over Mode	When a ".ofz" file is executed, the user has the option of either flashing or of running the Boot ROM contents in that ".ofz" file, "replacing" the currently-running BootROM image without flashing. While very convenient, one must beware that most BootROM modifications must be tested by flashing and not doing take-over, because there are differences. HWInit, and OF's early stages, and even OF probe, should always be tested from a hard reset. Indeed, some bugs won't even manifest themselves with hard reset, but rather require an off/on power cycle.
NVRAM	Non-Volatile RAM. Holds settings that cannot be on mass storage but must still survive power cycles, including both OF settings such as the preferred boot device and OS settings such as the time zone and preferred display resolution. CMD-OPT-P-R clears it; in OF, `printenv` displays its OF contents. But beware: ????????the clearing code is after some parts of OF run, including NVRAM's OF partition interpretation; so the machine may still hang after all if NVRAM is messed up enough, requiring unplugging of AC power, removal of battery, and waiting hours for bulk capacitance or shorting CUDA pins 1,39,40. This situation is rather unfortunate.
"`.ofz`" file	Output file, ie, `Yosemite.ofz`, located in BuildResults after a sucessful build. When loaded and run from inside the OF User Interface, it allows in-place execution or flashing of a new BootROM.
"`.fmwr`" file	Same as .ofz file, except automatically begins flashing, draws a graphical progress thermometer, and leaves behind a flag. For use by OS installers for BootROM updating.
"`tbxi`" file	File of MacOS filetype 'tbxi' that the boot search loads and executes. For English MacOS, its creatortype is 'chrp' and its name is "Mac OS ROM". It is assumed to be of "chrp-boot" format; this means that it is taken to be a text file with an expandable HTML-like "`<tag>` xxxx `<\tag>`" structure. Some of the tags are machine compatibility lists, some are icons, and one is a compressed image of the previously-in-ROM-MacOS-part.
Top-Of-Trunk, TOT	The latest revisions of all source files at the current instant in time. Usually referred to in conjunction with a specifc BBS team entity, as in: "I just checked out and built the BootROM sources, so this is a top-of-trunk build".
Version Set	A named snapshot of the revisions of all source files belonging to a BBS team entity at a specific moment in time. It is a file containing a list of all source file names followed by a version number. Since the Version Set file is itself a checked in file, it too can undergo revisions and can be modified to have the exact mix of source file versions desired. Usually they are given very precise and descriptive names, such as "Yosemite_1.1_b8" or "Yosemite_1.1_GM". Version sets which have names such as "Yosemite_ForkThis" are ongoing-evolving and may actually be very close to top-of-trunk; in this case a version set is merely a way to prevent surprises. Version sets such as the aforementioned "Yosemite_1.1_GM" are more sacred; they are never changed; and they refer to specific released builds to SCM / factory. Version sets used to be implemented with a MPW mechanism called "NameRevisions", but NameRevisions do not have the load-carrying capacity required, nor can they themselves be audited in the way that a file full of revision numbers can.
Branch	A revision to a file that does not directly follow the previous revision and where later revisions will not necessarily follow. Branches are used, for example, when a project's version set is using a much lower revision of a file than top-of-trunk, a bug fix needs to be made, and it is impossible to incorporate the change to the top-of-trunk of the file and then add that to the version set, for reasons of undesirability of the "fix", risk of using top-of-trunk, or a dependency explosion.
Compile Time, Probe-Time, Run Time	Compile time, then: POST run, OF init, OF probe, OF runtime or User Interface time, OF handoff with Client Interface, OS run. talk about how code is interpreted and inline statments are exectued when
Fload, Byte-Load-File, Tokenize-List	fload is like a #include in the source code, and thus is a simple inline include of the text file inside another text file during compilation cmp byte-load-file. byte-load-file is like a probe-time (early runtime) load. cmp fload, tokenize-list. Tokenize-list is a compile-time include of the text file and wrapping for probe-time (early runtime) activation by byte-load-file. mention byte-load-file manual and automatic, and how those two ids work
MLB	Main Logic Board. That is, the Apple Yosemite PC board.
CHRP	Common Hardware Reference Platform. "Chirp". An attempt at defining a standard hardware platform, from a minimum feature set, plug-and-play, and software-to-hardware interface perspective, for Macintosh computers. This was considered useful for the short-lived Macintosh cloning effort in which multiple hardware vendors would supply computers that would run MacOS. Several of the CHRP specifications and the work done on it live on, in the form of the OF-3 feature set, the NewWorld ROM-in-RAM booting architecture, MacOS interrupt management, NVRAM structure, etc.
Big Endian	When a value is represented or stored into memory that is multiple-byte-precision, more-significant 8-bit bytes are presented first or stored in lower memory locations. For example, `0x11223344` is stored in memory as `+0:0x11`, `+1:0x22`, `+2:0x33`, `+3:0x44`. Motorola processors such as the 68000 family use big-endian representation.
Little Endian	When a value is represented or stored into memory that is multiple-byte-precision, less-significant 8-bit bytes are presented first or stored in lower memory locations. For example, `0x11223344` is stored in memory as `+0:0x44`, `+1:0x33`, `+2:0x22`, `+3:0x11`. Intel processors such as the 8086/Pentium family, plus the 6502, use little-endian representation.
GUI	Graphical User Interface. Industry-standard term relating to the moment-to-moment interaction between a machine and an operator; especially such an interface that is characterized by point-and-select input and possibly graphical output.
HI	Human Interface. Apple Computer's term for GUI.
BPS	BootPath-Search.
BootPath-Search	BootROM "middleware" that provides a layer between the device tree and device drivers and Multiboot and Mac-Boot; handles partition searching, device I/O trying, etc, so that Multiboot and Mac-Boot can be less cluttered to concentrate on GUI policy and high-level behavior.
OS Picker	Multiboot.
Mac-Boot	BootROM "applicationware" that mimics the Macintosh StartSearch behavior that implements in OF what was implemented in the large MacOS ROMs in previous machines.
Multiboot	BootROM "applicationware" that implements a GUI choice of boot options.
BootInfo	CHRP-Boot format.
CHRP-Boot	File format for identifying an OS; see "`tbxi`" file.
Secondary Loader	An OS loader; any program that OF boots; the "`tbxi`" file is a Secondary Loader.
Platform, Machine, CPU, Product	The specific machine main logic board hardware model or family; for example "Yosemite CPU" (or "Yosemite platform" or "Yosemite machine" or "portable machines"). Quite often in this context, "CPU" refers not to the processor but instead to the product.
Project	CPU, or a family of CPUs that are very, very closely related and/or ship at the same time.
MMU	Memory Management Unit; the part of the CPU that handles the concept of virtual address translation. MMU is used in this document as a generic term.
Configuration Space, PCI Config Space	PCI Configuration Space read/write cycles are in a separate "memory" space from CPU memory (though of course for CPU access it is ultimately accessed through a hardware memory-mapped space bottleneck). It is a geographic address space of PCI device control registers; that is, PCI hardware devices' "Config Space" register sets occupy hardware-schematic-determined addresses in a single global "PCI Config Space". PCI configuration space registers can then be written to in order to assign them to places in the normal CPU address space memory map (do not confuse this with CPU virtual addressing), as well as to control such parameters as cache snooping, bus latency, etc, and to provide device type, revision, and manufacturer information.
Binding	A document that defines the application of OF to a specific problem. For example, the document "PCI Bus Binding to [IEEE Std. 1275-1994 Standard for boot firmware]" describes how the generalities of OF are brought to bear on the specifics of the PCI bus. It defines the format of the data structures of the "reg", "assigned-addresses", "ranges", and other properties. Without this document, one cannot know how the data inside these properties represents the PCI bus hardware, because OF itself is bus-agnostic.
Alarm	Periodic task services. Alarm tasks are installed with the "`alarm`" OF call. Alarm tasks are called periodically, much like a MacOS VBL or Time Manager task. The alarm routine is executed in the context in which it was installed; that is, the current `my-self` context pointer is set to that "belonging" to the alarm task and is then restored prior to resumption of execution of the "foreground" code.
Quiesce	Shutdown task services. Quiesce tasks are installed with the "`set-quiesce`" OF call. Before OF exits, all Quiesce tasks are executed, much like MacOS Shutdown Manager tasks. Many OF drivers and other software put hardware in a state that OS drivers do not like, and it may be undesirable (though perhaps more correct) to put such hardware states back at the conclusion of each `close-dev` call (again, it would be more correct to leave drivers open for the entire OF session, but that is not possible because certain service options are irrevocably bound to a driver context at `open-dev` time, and even though in theory multiple `open-dev`'s on the same device driver should work, this probably does not work (such a driver would have to manage hardware state for multiple callers)).
Phandle, p-handle, ph	Pointer to the OF system data structure that defines a node in the Device Tree ("package handle"). With a phandle, one can access properties (but not execute code; this requires an execution context; see "instance handle").
Active-package	The current phandle; it is what changes when the "`dev`" command is used.
Instance Handle, ihandle, ih	Pointer to the OF system data structure that defines an execution context. It is returned from calls such as `open-package` and `open-dev`. With an ihandle, one can call routines by name, MacOS Code Fragment Manager (CFM) - style. An instance handle establishes the current stack, variable world, alarm/quiesce/etc contexts, and routines (words) to be able to be called. An ihandle implies a phandle; that is, an ihandle has an associated phandle but not necessarily vice versa.
My-self	The instance handle of the currently executing code. This can change from moment to moment as different code in different packages and drivers runs. It is much like the MacOS 68x A5 register or PPC TOC register usage.
Trampoline Code	The part of the MacOS secondary loader that acts as a translator between OF and MacOS; it sets up data structures for I/O hardware addresses and interrupt sources, such as Universal Tables, that were originally in ROM; it accesses the Device Tree by means of OF Client Interface callbacks to gather this information. It builds the OS runtime "Name Registry", which is an OS-runtime copy of the Device Tree. The Name Registry actually ends up containing more information than just the raw Device Tree; the names of such nodes and properties are usually prefaced with "`AAPL`" or "`APL`".
STM	Serial Test Manager; provides the factory process EMMO station with a means of executing and/or downloading code. In the BootROM, it is implemented by as a set of MiniNub commands; that is, the MiniNub really is merely a superset of STM.
EMMO	Enhanced "Mac Minus One [one = a mac]". A test station at the factory. After the main logic board (MLB) is stuffed, it is run through ICT, after which it runs thru EMMO, after which it is assembled into an enclosure and downloaded with high (OS)-level test code (Banzai/Ichiban/PowerTest). EMMO is a vacuum "bed of nails" fixture which sucks down and makes electrical contact with the MLB (thus eliminating the need to plug-in connectors (but therefore also emphasizing the importance of later OS-level testing of data thru the connectors, which is very important as that is often a weak link)), powers it up, and uses STM to run tests. Meanwhile, not only must the test results pass, but also electrical characteristics are monitored and must fall within emperically derived values.
ICT	In-Circuit Test. A factory vacuum bed-of-nails test fixture which sucks down and makes electrical contact with the MLB and verifies against electrical opens and shorts, and also does low-power probing of passive components such as coils, resistors, and capacitors. The board may or may not be powered up during various phases of ICT.
Banzai, Sapporo, Ichiban, PowerTest	High (OS)-level factory test code which runs after the machine has been fully assembled but not yet been loaded with the final shipping software. This test code runs for an extended period of time (hours) while the machines spend time in burn-in time-wasting "towers" (necessary to keep machine production constant at several units/minute while still allowing many hours for testing). The emphasis is on running tests that exercise connection paths, such as loopback thru rear panel connectors, high-level OS behaviors implied by hardware features (such as QuickTime video loopback), which are not so easily tested with ICT or EMMO, and time-consuming items such as repeated full memory tests. The different names (Banzai, etc) refer to various components: There is a "pre-burn" station that downloads software; then the software runs on its own, then there is a "post-burn" station that collects results; in addition, since diagnostics come from various places at Apple and 3rd-parties, there is shell software to launch and collect results and present a testing API.
ASIC	Application-Specific Integrated Circuit. Used to refer to any very large scale integration (VLSI) device, such as most "difficult" controllers such as FireWire, Grackle, etc, but especially refers to a company-specific device, created by its engineers (not 3rd parties), and only in its own products. A prime example is Grand Central / Heathrow / Paddingon / Uni-N. Another example might be CUDA, but that is more of a microcontroller with some added features than a true ASIC. Another example is the ATI ASICs on its graphics cards.

SPECIFIC

Machine-Specific BootROM Engineering Information

S.1. Overview

S.1.1. Basic Yosemite machine description

Desktop machine, minitower configuration
3 PCI 64-bit 33-MHz slots, 1 PCI 32-bit, 66-MHz slot for video card
4 RAM slots, PC-100 type, non-interleaved, I2C declaration, 1-GByte max
Programmable clock divider for CPU core and L2 cache; typical configuration is 400 (varies with configuration)-MHz CPU, 200 (varies with configuration)-MHz 512M/1G (varies with configuration)-Byte L2 Cache, 100-MHz RAM, 66-MHz primary PCI, 33-MHz secondary PCI
A Motorola MPC106 "Grackle" memory controller / PCI controller forms the basic computer along with the CPU, RAM, and 1-MByte 8-bit Flash BootROM. The primary PCI bus from Grackle feeds a DEC 211154 PCI-PCI bridge which in turn feeds the 3 main PCI slots and motherboard devices. One of those motherboard devices is the Apple Paddington ASIC
Built-in FireWire, USB, ATA-3, ATA-4 (Ultra ATA)
Apple Paddington ASIC provides Macintosh legacy I/O
NVRAM, Apple Burgundy audio ASIC, CUDA real-time-clock/ADB/power/I2C/etc-controller
CDROM and ZIP drives on ATA-3 bus; main HD on ATA-4 bus; some configs have SCSI card and drive

S.1.2. Major new hardware components

FireWire
USB (continued from iMac; very new)
Ultra ATA (ATA-4)
Apple Burgundy audio ASIC
ZIP drive internal
ATI Rage 128 Video card bundled

S.2. Trivial deltas, makefile issues, etc

This section describes the fist-pass obvious items that needed to be changed for the new Yosemite machine. These can and should be done before real hardware arrives.

Other sections of this document will describe in more detail the many things that need to be changed to support a new machine, indeed, the information herein will most likely be insufficient and irrelevant, in part because a new machine will have unforeseen requirements. However, a few gross steps which are relatively mechanical and apply to almost any project can be described here in summary first.

In order to create an Open Firmware build target for a new machine, a few "easy" tasks must be performed before the more in-depth coding (such as debugging and addition of new functionality) begins.

S.2.1. Creation of a BBS build target

Making a new build target for the BootROM team is done by adding to:

{BR}:Make:Build

S.2.2. Creation of new project-specific files

Generally, the easiest thing to do is to choose a previous project that the new project is closest to, copy the files, run the MPW orphanfiles command on them, modify them, and manually check them in for the first time (BBS will be used for checkin/checkout from there on). Project-specific directories (projector directories, or "sub"-projects), also need to be created.

Project-specific files for Yosemite, for example, are:

{BR}:Documentation:yosemite_bootrom.htm
{BR}:BuildSpecific:Yosemite:Yosemite.make
{BR}:BuildSpecific:Yosemite:Yosemite.s
{BR}:POST:HardwareInit.s, and especially read the policy comments
{BR}:POST:*.s; files that are INCLUDEd by HardwareInit.s; note that the same files are used both as header files for data structures as well as code files; they are INCLUDEd once with IncludeTime equ 0, and then a second time with IncludeTime equ 1; for Yosemite, this included the following:

Diagnostics.s
MiniNub.s
Processors.s
Grackle.s
IOController.s
Sound.s
PowerMgmtMicro.s

{BR}:OF:OFSources:Projects:Yosemite:Yosemite.fth
{BR}:OF:OFSources:Projects:Yosemite:FINISH-DEVICE-TREE.of
{BR}:OF:OFSources:Projects:Yosemite:THE-FILES.of
{BR}:OF:OFSources:Projects:Yosemite:THE-TREE.of

S.2.3. Addition of new conditional-compile cases

For the unfortunate conditional-compile cases that are spread thoughout the source files, these may need to be augmented for the new machine. In general, conditional compile for specific machines is messy, and some effort has been made to reduce its prevalence as much as possible. There are two major conditional compile flags indicating a specific machine build:

foryosemite -- Checked for in PowerPC assembly language files (".s" files), consisting of Boot Block, Hardware Init (most machines), Diagnostics, etc.
FOR-YOSEMITE -- Checked for in Open Firmware FORTH language files (".of" files), consisting of OF sources, as well as the OF PPC Assembler files (".fas" files), consisting of the OF Kernel and Hardware Init (some machines).

S.2.4. Addition to tables, structures, etc, in certain critical files

The changes described here are in addition to creating new BBSBuild entries, makefile entries, and project-specific files; these changes may or may not be conditional compile cases.

For Yosemite, Hardware Init changes had to be made before the ROM could truly come up (Open Firmware itself seemed to run on an older Macintosh unit using take-over mode):

POST:Grackle.s

{BR}:OF:OFSources:Kernel:NVCONFIG-CHRP.def

Even though the OF Kernel is mostly platform-independent, being given runtime parameters from Hardware Init, there are some things that are conditionally compiled and are very machine-specific and needed for execution:

OFSources:Kernel:Kernel.fas:"config-macio"

S.2.5 Versioning and Machine ID

S.2.5.1 xxxx

The root node ("/") " model" property content is "powermac1,1".

S.2.5.2 xxxx

talk about the other versioning string, and how it changed

S.2.5.3 xxxxxx

talk about how the installer needs to check this; talk about the new mechanism proposed

Added a /rom/boot-rom property called info that includes the information about the

BootROM sections for the OS flasher,

otROM:OF:OFSources:Projects:Core99:FINISH-DEVICE-TREE.of' # checked in on 5/24/99 6:21:12 PM

\ <BR38> 5/24/99 JDH [2336103] Add the /rom/boot-rom "info" property

S.3. Minor Deltas

This section describes the BootROM changes needed between Yosemite and the next closest machine that are nontrivial enough to not be in the "Basics" section above, but are nevertheless straightforward.

S.3.1. Hardware Init

See General section below for overall description.

xxxxx yos specifics

S.3.2. Open Firmware

S.3.2.1. Device Alias settings

The alias settings must be set and maintained to be correct at all times during project development, not only because it is convenient to be able to use alias shorthand when typing in the User Interface, but because BootPath-Search relies on certain aliases to be correct.

In particular, BPS cares about no-boot, last-boot, hd, and cd; it may also care about second-boot and first-boot. See BPS documentation for more information. Without proper settings for these values, and if no working device is specified in NVRAM "boot-device", then the boot search may be slow or erratic.

Alias settings are defined in the THE-TREE.of file and are property arrays in the /aliases node.

See elsewhere for a discussion on the "@80000000" following the initial "/pci" in the paths below.

The value (rhs) expansion of an alias name (lhs) is not limited to a single string; it can be an array of strings.

DevAlias Settings for Yosemite And Descriptions

Name (lhs)	Value (rhs)	Description
`pci`	`/pci@80000000`	This points to the PCI controller (sometimes also referred to as a "bridge", but remember that it is a "memory-bus-to-PCI bridge", not a "PCI-PCI bridge") half of the MPC 106 "Grackle" memory controller/PCI controller.
`bridge`	`/pci@80000000/@d`	This points to the DEC 21154 PCI-PCI bridge that is located downstream of the MPC 106 "Grackle" PCI controller. Since 3 of the PCI slots and most onboard devices are located below this bridge, it is possible, for example, to address a card as "`bridge/@2`".
`mac-io`	`/pci@80000000/@d/mac-io`	This points to the Apple Paddington legacy I/O ASIC. Paddington roughly equals the previous Grand Central and Heathrow devices.
`via-cuda`	`/pci@80000000/@d/mac-io/via-cuda`	This points to code in `VIA-CUDA.of` that allows setting of the CUDA real time clock, doing I2C communciations to many devices, including reading RAM slot declaration ROMs. The CUDA, an independent microcontroller, needs to be talked to via the VIA, a set of general purpose I/O registers inside the Apple Paddington ASIC.
`i2c-serial`	`/pci@80000000/@d/mac-io/via-cuda/serial`	This points to a "serial" driver `VIA-CUDA.of` (for Yosemite) that operates over the I2C bus. Useful for debugging, and future non-Yosemite machines that will not have a serial port at all, not even one that doesn't have a connector.
`rtc`	`/pci@80000000/@d/mac-io/via-cuda/rtc`	See above; this points to the "rtc" (real time clock) code/node in `VIA-CUDA.of` (for Yosemite) that accesses the time of day clock in CUDA.
`adb-keyboard`	`/pci@80000000/@d/mac-io/via-cuda/adb/keyboard`	Points to ADB keyboard driver used for console I/O (but also see USB and Psuedo-HID) (for Yosemite, the keyboard driver is defined inline in `HEATHROW.of` where it includes (`fload`s) `ADB-KBD.of`).
`adb-mouse`	`/pci@80000000/@d/mac-io/via-cuda/adb/mouse`	Same as adb-keyboard above.
`sound`	`/pci@80000000/@d/mac-io/davbus/sound`	Points to sound driver used for nothing apparently (the driver is opened and the OF global `_audio-ihandle` is set but nobody uses it) (for Yosemite, the sound driver is defined inline in `HEATHROW.of` where it includes (`fload`s) `BURGANDY.of`).
`enet`	`/pci@80000000/@d/mac-io/ethernet`	Points to Ethernet driver that is used for loading files over the network using `TFTP` or `BOOTP` protocols; used, ie, by Multiboot for net booting; code defined in `BMAC.of`.
`scca`	`/pci@80000000/@d/mac-io/escc/ch-a`	Points to serial driver (for Yosemite, the serial driver is defined inline in `HEATHROW.of` but run-time-loads (`byte-load-file`s) `SCC.of`). For the first serial port (A). Connections from the Paddington (=Heathrow) ASIC go to the Modem slot.
`sccb`	`/pci@80000000/@d/mac-io/escc/ch-b`	Points to serial driver. For the second serial port (B). Not used; connections go to the front panel daughterboard which was going to have IRDA, but IRDA was cancelled.
`nvram`	`/pci@80000000/@d/mac-io/nvram`	Points to NVRAM read/write driver; different machines implement it differently (inside CUDA, separate SRAM (Yosemite), partition in BootROM (post-Yosemite). This is low-level only; the format of the NVRAM data, which is now organized into individually controlled and checksummed partitons, is defined by `NVRAM-CHRP.of` and `NVCONFIG-CHRP.def` (for Yosemite, the NVRAM driver is defined inline in `HEATHROW.of` where it includes (`fload`s) `HEATHROW-NVRAM.of`).
`ide0`	`/pci@80000000/@d/mac-io/ata-3@20000`	Points to Standard ATA driver cell in the Paddington ASIC (hence it's under `mac-io` node).
`cd`	`/pci@80000000/@d/mac-io/ata-3@20000/disk@0`	Points to Standard ATA driver. For Yosemite, we know that the most-often cabled config has the CD on Standard ATA device 0 (master). This alias might be required for best Boot Path Search / Multiboot operation.
`zip`	`/pci@80000000/@d/mac-io/ata-3@20000/disk@1`	Points to Standard ATA driver. For Yosemite, we know that the most-often cabled config has the Zip on Standard ATA device 1 (slave). This alias might be required for best Boot Path Search / Multiboot operation.
`ide1`	`/pci@80000000/@d/pci-ata@1/ata-4@0`	Points to Ultra ATA driver motherboard device on the PCI bus (hence it's not under `mac-io` node).
`hd`	`/pci@80000000/@d/pci-ata@1/ata-4@0/disk@0`	Points to the "main" hard drive on most Yosemite configs; we know that it's Ultra ATA device 0 (master). This alias might be required for best Boot Path Search / Multiboot operation.
`ultra0`	`/pci@80000000/@d/pci-ata@1/ata-4@0/disk@0`	Points to Ultra ATA bus, device 0 (master ), assuming ATA protocol. Unlike Standard ATA, currently (10-May-1999) the Ultra ATA driver does not autodetect at Open time ATA vs. ATAPI protocol -- thus "disk" forces the ATA driver ("cdrom" forces the ATAPI driver). See section 9, "Open Issues".
`ultra1`	`/pci@80000000/@d/pci-ata@1/ata-4@0/disk@1`	Points to Ultra ATA bus, device 1 (slave), assuming ATA protocol; see above.
`usb`	`/pci@80000000/@d/usb@6`	Points to code in `USB-OPENHCI.of` that communicates with the USB controller device on the PCI bus; is has as clients such drivers as `psuedo-hid/keyboard/mouse`, and for the future (10-May-1999) mass storage device drivers are also planned.
`fw`	`/pci@80000000/@d/firewire`	Points to FireWire node. In shipping Yosemite, currently (10-May-1999) there is no "expansion ROM" code, in the Boot ROM or elsewhere, associated this device, and OF does nothing with it; there are no drivers (this will change, especially for future machines); in fact the "firewire" name is added by code in `FINISH-DEVICE-TREE.of` since without node code we would have a default "pci1234,5678" style name.
`keyboard`	`/psuedo-hid/keyboard`	Points to a generic keyboard input driver node that is a multi-selector between various services, such as ADB and USB keyboards, so that they all work at the same time ("dueling keyboards").
`mouse`	`/psuedo-hid/mouse`	Points to a generic mouse input driver node that is a multi-selector between various services, such as ADB and USB mice, so that they all work at the same time ("dueling mice").
`usb-keyboard`	Return value determined at alias inquiry time	Instead of containing a static rhs string, this alias points to a word which is executed when the alias resolution is requested; this word returns the path, determined at runtime, of the driver currently associated with the appropriate ihandle OF global variable, "`_usb-keyboard`".
`usb-mouse`	Return value determined at alias inquiry time	Same as `usb-keyboard` above.
`no-boot`	/`pci@80000000/pci-bridge@d/mac-io@5/fdc`, `/pci@80000000/pci-bridge@d/mac-io@5/scsi, /pci@80000000/pci-bridge@d/mac-io@5/ata-3@21000`	Note that more than one string is in the rhs. This is a signal to boot path search of which ranges of devices to not consider. Why are they in the device tree at all? OS and debugging requirements. This alias might be required for best Boot Path Search / Multiboot operation.
`last-boot`	`/pci@80000000/pci-bridge@d/mac-io@5/ethernet`	This is a signal to Boot Path Search of which device to consider last (after trying all others) if booting has to resort to the "blinking folder" search. Note that `first-boot` and `second-boot` are also available; see BootPath-Search documentation. This alias might be required for best Boot Path Search / Multiboot operation.
first-boot	N/A	Not defined in Yosemite, but included here for completeness. This is a signal to Boot Path Search of which device to consider first (before trying all others) if booting has to resort to the "blinking folder" search. This alias might be required for best Boot Path Search / Multiboot operation.
second-boot	N/A	Not defined in Yosemite, but included here for completeness. This is a signal to Boot Path Search of which device to consider second (right after trying the "first" device, if so defined) if booting has to resort to the "blinking folder" search. This alias might be required for best Boot Path Search / Multiboot operation.
`screen`	`/pci@80000000/ATY,RagePro_PCI66@10`	The screen alias, if it doesn't already exist (ie, by means of a hardcoded alias), it generated by code in `RESOLVE.of`.

The process was that we started with Gosamer boot rom settings, then deleted OF drivers (ie, for built in video) that it did not have, etc.

Some devices for which there are no I/O connections (but may still have device cells implemented in the Paddington Mac-IO ASIC) are still included, for various reasons:

SCSI is included in the device tree and has an OF device driver (but no OF device alias reference) because MacOS or MacOS applications (such as earlier versions of Drive Setup) have problems otherwise.
The FDC (SWIM3 Floppy) node and driver are included for original debugging purposes and were left in.
The SCC (Serial Port) node, OF driver (for console I/O), and the code that just dumps data to the SCC device in certain debugging modes, such as the Mininub or the OF logger, are left in for debugging and development purposes.

S.3.2.2. Slot Names

The slot-names properties describe available plug-in connectors. They contain a bit vector of available connectors within a device's realm and a list of names of how those connectors are labelled. They are generally hard-coded for main logic board (MLB) connections, but can be dynamically generated also (ie, for PCI-PCI expansion chassis handing).

For example, if a device has 10 outputs, of which 4 are wired to user-connectors and 6 are not used or hardwired to other internal devices, then there should be 4 slot-names properties each describing the connectors' name and if possible a bit vector of its position within the 10.

One of the uses of this information is for high-level software such as Apple System Profiler (ASP) to display user instructions with the real names as silkscreened on the board.

For Yosemite, the slot-names properties are as follows:

Yosemite slot-names Properties

Path	Setting	Description	Source File
`/pci`	`0x10000 = bits [2:4]` `"J12"`	Grackle MPC 106 main PCI controller; slot name is that of the "video" PCI slot	`BUS:GRACKLE.of`
`/pci/bridge`	`0x1C = bit [16]` `"J11"` `"J10"` `"J9"`	DEC PCI-PCI bridge on motherboard; slot names are those of the "regular" PCI slots	`BUS:GRACKLE-PCI.of`
`/pci/bridge/?`	Algorithm in PCI-PCI.of	Bridges on cards; expansion chassis	`COMMON:PCI-PCI.of`
`/memory`	`0xF = bits [0:3]` `"DIMM0/J19"` `"DIMM1/J20"` `"DIMM2/J21"` `"DIMM3/J22"`	RAM DIMM slots	`*:FINISH-DEVICE-TREE.of`
`/pci/bridge/mac-io/scca`	`0x1 = bit [0]` `"Modem"` if detected	Serial port channel A	`BUS:HEATHROW.of`
`/pci/bridge/mac-io/sccb`	`0x1 = bit [0]` `"IrDA"` always, even though Yosemite does not have IrDA in shipping config	Serial port channel B	`BUS:HEATHROW.of`

It is unclear to the author whether or not one could make an argument that connectors on the rear panel -- Analog audio I/O, USB, FireWire, Ethernet, ADB, even Power -- should have slot-names properties.

S.3.3. RTAS

xxxxxxxxxxx

S.4. Major Deltas

This section describes any wholly new compontents needed in the BootROM for Yosemite and perhaps major changes to an existing component.

S.4.1. Hardware Init

S.4.1.1. Boot block

Starting with Yosemite (and post-original iMac releases), the out-of-reset code flow and layout has changed to follow Flash ROM topography so as to allow independent updating of "boot" (out of reset), "main", and "recovery" blocks to protect against flash accidents (interruptions). Yosemite's implementation is fairly general; however with later machines there will be machine-specific "configuration" information stored in Flash BootROM as well. See the description in the General section below.

S.4.2. Open Firmware

S.4.2.1. ZIP support

The ATA-3 ATAPI driver used to not work with some CD drives and all ZIP drives due to an assumption of block size.

S.4.2.2. Ultra ATA support

A new driver was acquired from some unknown source, upgraded by Dave Carlton, and installed in the sources.

S.4.2.3. Mac-Boot and BootPath-Search Work Continuation

Development and bug fix continuation from iMac to support new features and do correctly what was done as a quick kludge for the iMac timeframe.

S.4.2.4. lots and LOTS of other stuff - get from delta list in search window ???????

S.4.3. RTAS

xxxxxxx

S.5. Exhaustive List Of Yosemite-Related Changes

The box below lists all after-iMac, Yosemite-project-specific changes to all BootROM sources.

It the result of a search for all Yosemite conditional compile and Yosemite specific file references plus all changes by Bob Bradley and Ben Koning, and then filtered to get rid of changes made for or before iMac, after Yosemite GM,changes obviously not for Yosemite, more than one example of repetitive things, compiler dumps, duplicates of any kind, "comment-only" changes, end-of-conditional compile comments, spurious search hits (data, constants, embedded OS drivers), changes that cancel one another out, and obvious code irrelevancies. Each search result line was then truncated to show only a (still-searchable) subset of the BBS comment and filename and location.

This list excludes (does not include) numerous contributions -- new components and bug fixes -- that made their debut on Yosemite but are not specifically targeted for Yosemite only. In particular, Ron Hochsprung improved just about everything. Again, this list excludes relatively-new components that shipped on iMac (USB and BootBlocks). It is not even guaranteed to be complete even for Yosemite-specifics; a crucial bug fix may have been made by other than Yosemite personnel that is for the Yosemite project and timeframe that was not Yosemite code-specific; for that, the reader is directed to the various BBS scripts that can create deltas between version sets.

The list is pastable into MPW for triple-clicking and pressing ENTER to see the actual change in context; one must first do the MPW command "set -e BR YourBootROMDirectory". Due to major file changes, some of the file line number may not be exact in all cases.

Hand-Filtered Exhaustive List of Yosemite-Specific Source Changes

set -e BR YourBootROMDirectory

File "{BR}:Make:Build"; Line 363 # This is needed so that BBS can show all the builds in the menu

File "{BR}:Make:Build"; Line 57 # Add Yosemite build.

File "{BR}:Make:BootROMCommon.make"; Line 53 # Added defines for hasSysModuleEEPROM and

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 103 # Added defines for kNumBanks and

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 104 # Added builds of seperate 1MB and 4MB ROM

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 105 # Removed an extra quote that was generating

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 107 # Added ROM size and layout info for write-

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 109 # Changed to use ADB-KBD.of instead of ADB.of

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 112 # Set what I think are more correct address

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 114 # Get rid of using ROMVersion.fo, which is

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 117 # First checked in; only obvious

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 35 # Updated version and build date

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 43 # Add new file PSUEDO-USB.of

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 44 # Changed version and build date for the b4

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 44 # Add missing PSUEDO-HID.of

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 45 # Removed FIREWIRE-NODE.of

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 49 # Add FIREWIRE-NODE.of

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 54 # Updated version to A3. Also updated the

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 54 # Replace CI-WORDS.of with CLIENT-INTERFACE

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 66 # Updated version to D5 and build date to

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 67 # Changed the feature control value to clear

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 76 # Added Sound.s to the dependency list for

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 77 # Changed SystemIDRegisterAddress to account

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 79 # Removed MESH.of from the OF sources list

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 81 # Removed kNumBanks define since it defaults

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 82 # Changed defines to account for hardware

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 87 # Added IOCtrlIDSEL define and changed the

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 92 # Added defines for ExternalPCIBridgeIDSEL

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 97 # Added define for supportGossamerDVT to the

File "{BR}:BuildSpecific:Yosemite:Yosemite.make"; Line 98 # Integrated changes for write-protected boot-

File "{BR}:BuildSpecific:Yosemite:Yosemite.s"; Line 25 # Commented out constant leave flashing enabled

File "{BR}:BuildSpecific:Yosemite:Yosemite.s"; Line 29 # Cleared modem power bit (active low) in

File "{BR}:BuildSpecific:Yosemite:Yosemite.s"; Line 31 # Removed usedFixedROMSettings equate as we now

File "{BR}:BuildSpecific:Yosemite:Yosemite.s"; Line 63 # forYosemite equ 1 # should go away - move

File "{BR}:POST:Grackle.s"; Line 1002 # ifdef forYosemite

File "{BR}:POST:Grackle.s"; Line 1020 # ifdef forYosemite

File "{BR}:POST:Grackle.s"; Line 107 # Enabled SERR on Grackle and the DEC Bridge and enabled SERR

File "{BR}:POST:Grackle.s"; Line 1085 # ifdef forYosemite

File "{BR}:POST:Grackle.s"; Line 113 # Added OptimizeMemorySettings routine to optimize how Grackle is

File "{BR}:POST:Grackle.s"; Line 130 # Optimizations for Yosemite. Reduced the activate to pre-charge

File "{BR}:POST:Grackle.s"; Line 136 # Optimizations for Yosemite. Enabled write store gathering

File "{BR}:POST:Grackle.s"; Line 144 # Change GetSysIDReg to account for Yosemite hardware changes

File "{BR}:POST:Grackle.s"; Line 146 # Changed L2 cache info table to account for Yosemite hardware

File "{BR}:POST:Grackle.s"; Line 148 # Added bus speed timing entries for 126mhz to 140mhz in 1mhz

File "{BR}:POST:Grackle.s"; Line 150 # Changed TS_WAIT_TIMER values for RAM configs greater than 100mhz

File "{BR}:POST:Grackle.s"; Line 160 # Added conditionalized support for dynamically calculating the

File "{BR}:POST:Grackle.s"; Line 165 # forYosemite with forDapple.

File "{BR}:POST:Grackle.s"; Line 172 # Changed the Yosemite portions of GetSystemToPCIRatio and

File "{BR}:POST:Grackle.s"; Line 175 # Added RAM configs for 100mhz, 120mhz, and 133mhz SDRAM and

File "{BR}:POST:Grackle.s"; Line 183 # Changed GetPCIFrequency to use the bus timing table, if

File "{BR}:POST:Grackle.s"; Line 2107 # ifdef forYosemite

File "{BR}:POST:Grackle.s"; Line 2197 # ifdef forYosemite

File "{BR}:POST:Grackle.s"; Line 2241 # ifdef forYosemite

File "{BR}:POST:Grackle.s"; Line 2533 # ifdef forYosemite

File "{BR}:POST:Grackle.s"; Line 2567 # ifdef forYosemite

File "{BR}:POST:Grackle.s"; Line 2758 # ifdef forYosemite

File "{BR}:POST:Grackle.s"; Line 2908 # ifdef forYosemite

File "{BR}:POST:Grackle.s"; Line 2969 # ifdef forYosemite

File "{BR}:POST:Grackle.s"; Line 3252 # ifdef forYosemite

File "{BR}:POST:Grackle.s"; Line 3268 # ifdef forYosemite

File "{BR}:POST:Grackle.s"; Line 34 # Turned CF_LOOP_SNOOP back on, on Yosemite, as the processor

File "{BR}:POST:Grackle.s"; Line 3470 # ifdef forYosemite

File "{BR}:POST:Grackle.s"; Line 36 # Increased REFREC in Grackle MCCR3 for extra margin on some

File "{BR}:POST:Grackle.s"; Line 38 # Increased DEC bridge arbiter priorities for the secondary bus on

File "{BR}:POST:Grackle.s"; Line 40 # Turn off CF_LOOP_SNOOP on Yosemite. Yosemite puts the cache in

File "{BR}:POST:Grackle.s"; Line 45 # Increased ROM timings when running at 100, 120, and 133mhz to

File "{BR}:POST:Grackle.s"; Line 47 # Changed the default SDRAM clock enable bits to also disable the

File "{BR}:POST:Grackle.s"; Line 49 # Changed the DisableUnusedSDRAMClocks routine to check for old

File "{BR}:POST:Grackle.s"; Line 54 # Added code to disable unused SDRAM clocks. We now look in NVRAM

File "{BR}:POST:Grackle.s"; Line 59 # Changed the DEC bridge settings to turn off memory write

File "{BR}:POST:Grackle.s"; Line 72 # Updated Yosemite system bus speed info tables for 133mhz.

File "{BR}:POST:Grackle.s"; Line 73 # Changed REFINT and PGMAX values for system bus speeds of 100,

File "{BR}:POST:Grackle.s"; Line 78 # Improved the routine to optimize memory settings in Grackle. It

File "{BR}:POST:Grackle.s"; Line 862 # ifdef forYosemite

File "{BR}:POST:Grackle.s"; Line 90 # Changed RAM timing table for Yosemite to replace one of the

File "{BR}:POST:Grackle.s"; Line 906 # ifndef forYosemite

File "{BR}:POST:Grackle.s"; Line 94 # Changed DEC bridge settings to optimize performance and work

File "{BR}:POST:Grackle.s"; Line 98 # Set the NO_SERIAL_CFG bit in Grackle PICR2 on Yosemite to work

File "{BR}:POST:IOControllers.s"; Line 108 # Set the arbiter bypass bit if useRonsSettings and

File "{BR}:POST:IOControllers.s"; Line 113 # Added support for bypassing the internal PCI arbiter

File "{BR}:POST:IOControllers.s"; Line 35 # Re-wrote portions of ReadIIC_EEPROM to use the newer Cuda

File "{BR}:POST:IOControllers.s"; Line 3989 # ifdef forYosemite

File "{BR}:POST:IOControllers.s"; Line 44 # Changed SendCudaCmd to fix problems when only sending data

File "{BR}:POST:IOControllers.s"; Line 54 # [2245994, 2266206, 2278084, 2280669] Changed SendCudaCmd

File "{BR}:POST:IOControllers.s"; Line 62 # Fixed problems with some of the Cuda error handling code

File "{BR}:POST:IOControllers.s"; Line 70 # Added a delay when calling sendByte1 on Yosemite. If we do

File "{BR}:POST:IOControllers.s"; Line 79 # Changed GetExternalCacheCode to return 0 on machines with

File "{BR}:POST:IOControllers.s"; Line 83 # Changed DetermineIICAddr to support the 4th DIMM slot on

File "{BR}:POST:Processors.s"; Line 43 # Moved BAT constants inside the includeTime conditional so

File "{BR}:POST:Processors.s"; Line 47 # Changed the default 750 HID0 value to set the DBP bit (Data

File "{BR}:POST:Sound.s"; Line 1282 # ifdef forYosemite

File "{BR}:POST:Sound.s"; Line 29 # [2287039] Changed InitSound to wait until Burgundy indicates it

File "{BR}:POST:Sound.s"; Line 326 # ifdef forYosemite

File "{BR}:POST:Sound.s"; Line 49 # Increased delay between each on/off transition of Burgundy to

File "{BR}:POST:Sound.s"; Line 51 # Added code to InitSound_Burgundy to turn off the sound power

File "{BR}:POST:Sound.s"; Line 57 # Removed detection of front headphones on Yosemite. There is no

File "{BR}:POST:Sound.s"; Line 593 # ifdef forYosemite

File "{BR}:POST:Sound.s"; Line 601 # ifdef forYosemite

File "{BR}:POST:Sound.s"; Line 63 # [2246001] Changed HandleDetects_Burgundy to account for wiring

File "{BR}:POST:Sound.s"; Line 87 # Changed GetSoundVolume to move the mtlr instruction inside the

File "{BR}:POST:Diagnostics.s"; Line 40 # Changed BAT mapping in the RunTests routine to map to an

File "{BR}:POST:Diagnostics.s"; Line 43 # [2270137] Added code to the RunTests routine to map each bank

File "{BR}:POST:Diagnostics.s"; Line 62 # Added check for pre-defined kNumBanks to avoid re-defining it

File "{BR}:OF:OFSources:Projects:Yosemite:Yosemite.fth"; Line 27 # Add conditional compile flag for the

File "{BR}:OF:OFSources:Projects:Yosemite:Yosemite.fth"; Line 29 # Turn off headers to save space and

File "{BR}:OF:OFSources:Projects:Yosemite:Yosemite.fth"; Line 30 # First checked in, based on Gossamer

File "{BR}:OF:OFSources:Projects:Yosemite:THE-FILES.of"; Line 24 # Remove FireWire dummy node; see

File "{BR}:OF:OFSources:Projects:Yosemite:THE-FILES.of"; Line 29 # Add FIREWIRE-NODE.of file

File "{BR}:OF:OFSources:Projects:Yosemite:THE-FILES.of"; Line 33 # First checked in, based on Gossamer,

File "{BR}:OF:OFSources:Projects:Yosemite:THE-TREE.of"; Line 105 # As per Ron's suggestion (Columbus:

File "{BR}:OF:OFSources:Projects:Yosemite:THE-TREE.of"; Line 109 # Blindly sync up with RH's change to

File "{BR}:OF:OFSources:Projects:Yosemite:THE-TREE.of"; Line 111 # First checked in, based on Gossamer

File "{BR}:OF:OFSources:Projects:Yosemite:THE-TREE.of"; Line 41 # Remove "@80000000" from paths in

File "{BR}:OF:OFSources:Projects:Yosemite:THE-TREE.of"; Line 47 # Changed model property to PowerMac1,1

File "{BR}:OF:OFSources:Projects:Yosemite:THE-TREE.of"; Line 47 # Fix bootpath-search hints now that

File "{BR}:OF:OFSources:Projects:Yosemite:THE-TREE.of"; Line 51 # Change "/pci/pci@d/xxx" to "/pci/pci-

File "{BR}:OF:OFSources:Projects:Yosemite:THE-TREE.of"; Line 53 # Update Open Firmware's version to

File "{BR}:OF:OFSources:Projects:Yosemite:THE-TREE.of"; Line 55 # Include FLOAD of /psuedo-usb (but not

File "{BR}:OF:OFSources:Projects:Yosemite:THE-TREE.of"; Line 57 # Add /aliases "last-boot" property with

File "{BR}:OF:OFSources:Projects:Yosemite:THE-TREE.of"; Line 64 # Change alias rhs's to track ide->ata

File "{BR}:OF:OFSources:Projects:Yosemite:THE-TREE.of"; Line 67 # Add "pci" alias; remove static "scsi

File "{BR}:OF:OFSources:Projects:Yosemite:THE-TREE.of"; Line 76 # Remove 'sd0'..'sd3' aliases: SCSI

File "{BR}:OF:OFSources:Projects:Yosemite:THE-TREE.of"; Line 79 # Changed keyboard and mouse to use to

File "{BR}:OF:OFSources:Projects:Yosemite:THE-TREE.of"; Line 86 # Add ATA Bus 1 (one) to /aliases "no-

File "{BR}:OF:OFSources:Projects:Yosemite:THE-TREE.of"; Line 87 # Change 'hd' alias to point to internal

File "{BR}:OF:OFSources:Projects:Yosemite:THE-TREE.of"; Line 92 # Add no-boot property under aliases

File "{BR}:OF:OFSources:Projects:Yosemite:FINISH-DEVICE-TREE.of"; Line 33 # Make sure CacheLineSize

File "{BR}:OF:OFSources:Projects:Yosemite:FINISH-DEVICE-TREE.of"; Line 38 # Remove <BR13>-<BR14> because

File "{BR}:OF:OFSources:Projects:Yosemite:FINISH-DEVICE-TREE.of"; Line 40 # Change <BR13> below to 1) do

File "{BR}:OF:OFSources:Projects:Yosemite:FINISH-DEVICE-TREE.of"; Line 42 # Hack to modify ATI video

File "{BR}:OF:OFSources:Projects:Yosemite:FINISH-DEVICE-TREE.of"; Line 45 # Change "/pci/pci@d/xxx" to

File "{BR}:OF:OFSources:Projects:Yosemite:FINISH-DEVICE-TREE.of"; Line 48 # USB POTPGT h#0A -> h#0B to

File "{BR}:OF:OFSources:Projects:Yosemite:FINISH-DEVICE-TREE.of"; Line 51 # Forgot the "encode-string"

File "{BR}:OF:OFSources:Projects:Yosemite:FINISH-DEVICE-TREE.of"; Line 52 # [2284831] Add code that at

File "{BR}:OF:OFSources:Projects:Yosemite:FINISH-DEVICE-TREE.of"; Line 58 # Remove creation of "dimm-s

File "{BR}:OF:OFSources:Projects:Yosemite:FINISH-DEVICE-TREE.of"; Line 65 # Add setting of platform-

File "{BR}:OF:OFSources:Kernel:ALLOC-MEM.of"; Line 25 # Prevent a NULL pointer call to FREE-MEM from

File "{BR}:OF:OFSources:Kernel:KERNEL.fas"; Line 34 # Setup the DEC 21154 bridge and then Paddington

File "{BR}:OF:OFSources:Kernel:KERNEL.fas"; Line 710 # defined? FOR-YOSEMITE [if]

File "{BR}:OF:OFSources:Kernel:NVCONFIG-CHRP.def"; Line 135 # F[ Fdefined? FOR-YOSEMITE F] [if]

File "{BR}:OF:OFSources:Kernel:NVCONFIG-CHRP.def"; Line 36 # Boot-device back to search-style "hd

File "{BR}:OF:OFSources:Kernel:NVCONFIG-CHRP.def"; Line 38 # Put explicit part number back in, on a CPU-

File "{BR}:OF:OFSources:Kernel:NVCONFIG-CHRP.def"; Line 42 # Further change default boot-device to "hd:,

File "{BR}:OF:OFSources:Kernel:NVCONFIG-CHRP.def"; Line 45 # Change "boot-device" default setting to

File "{BR}:OF:OFSources:Kernel:NVCONFIG-CHRP.def"; Line 53 # Go back to using non-generic names: Set

File "{BR}:OF:OFSources:Kernel:RESOLVE.of"; Line 44 # New OF global "chosen-partition" which, when

File "{BR}:OF:OFSources:Kernel:RESOLVE.of"; Line 59 # Add new OF global OPEN-DEV-ERROR that may

File "{BR}:OF:OFSources:Kernel:RESOLVE.of"; Line 84 # Fix several memory leaks (alloc-mem's without later

File "{BR}:OF:OFSources:Kernel:USER-INTERFACE.of"; Line 116 # Make $number tolerant of NULL string inputs

File "{BR}:OF:OFSources:Kernel:USER-INTERFACE.of"; Line 67 # Never use more than 25% of available memory

File "{BR}:OF:OFSources:Kernel:USER-INTERFACE.of"; Line 98 # Use new conditional GENERIC-NAME-DEFAULT

File "{BR}:OF:OFSources:Bus:GRACKLE-PCI.of"; Line 109 # F[ Fdefined? FOR-YOSEMITE F] [if]

File "{BR}:OF:OFSources:Bus:GRACKLE-PCI.of"; Line 241 # F[ Fdefined? FOR-YOSEMITE F] [if] \ for

File "{BR}:OF:OFSources:Bus:GRACKLE-PCI.of"; Line 259 # F[ Fdefined? FOR-YOSEMITE F] [if] \ Yosemite's

File "{BR}:OF:OFSources:Bus:GRACKLE-PCI.of"; Line 29 # For Yosemite, make sure main latency timer setting

File "{BR}:OF:OFSources:Bus:GRACKLE-PCI.of"; Line 31 # Note: USE-GENERIC? may not have been set yet when

File "{BR}:OF:OFSources:Bus:GRACKLE-PCI.of"; Line 35 # Change "pci" name to "pci-bridge" as per [2287975]

File "{BR}:OF:OFSources:Bus:GRACKLE-PCI.of"; Line 39 # Changed DEC Bridge settings to optimize performance

File "{BR}:OF:OFSources:Bus:GRACKLE-PCI.of"; Line 40 # Set CacheLineSize to 0 when initializing DEC PCI-

File "{BR}:OF:OFSources:Bus:GRACKLE-PCI.of"; Line 41 # Changed the slot names of the PCI slots on

File "{BR}:OF:OFSources:Bus:GRACKLE-PCI.of"; Line 52 # Disable probing of Paddington since the node

File "{BR}:OF:OFSources:Bus:GRACKLE.of"; Line 251 # F[ Fdefined? FOR-YOSEMITE F] [if]

File "{BR}:OF:OFSources:Bus:GRACKLE.of"; Line 32 # Added back generation of the reg property for Grackle.

File "{BR}:OF:OFSources:Bus:GRACKLE.of"; Line 33 # Changed the name of the 66mhz PCI slot on Yosemite to

File "{BR}:OF:OFSources:Bus:GRACKLE.of"; Line 355 # F[ Fdefined? FOR-YOSEMITE F] [if]

File "{BR}:OF:OFSources:Bus:GRACKLE.of"; Line 39 # Added code to GRACKLE-QUIESCE to set BSTORE_U in

File "{BR}:OF:OFSources:Bus:GRACKLE.of"; Line 439 # F[ Fdefined? FOR-YOSEMITE F] [if]

File "{BR}:OF:OFSources:Bus:GRACKLE.of"; Line 55 # Conditionalized setting of the FLASH_WR_LOCKOUT bit

File "{BR}:OF:OFSources:Bus:GRACKLE.of"; Line 68 # Added probing of PCI slots for Yosemite.

File "{BR}:OF:OFSources:Bus:GRACKLE.of"; Line 69 # Added slot-name property and probing for PCI slots

File "{BR}:OF:OFSources:Bus:HEATHROW.of"; Line 180 # F[ Fdefined? FOR-COLUMBUS Fdefined? FOR-YOSEMITE

File "{BR}:OF:OFSources:Bus:HEATHROW.of"; Line 436 # F[ Fdefined? FOR-COLUMBUS Fdefined? FOR-YOSEMITE

File "{BR}:OF:OFSources:Bus:HEATHROW.of"; Line 512 # F[ Fdefined? FOR-YOSEMITE F] [if]

File "{BR}:OF:OFSources:Bus:HEATHROW.of"; Line 554 # F[ Fdefined? FOR-YOSEMITE F] [if]

File "{BR}:OF:OFSources:Bus:HEATHROW.of"; Line 57 # [2260094] Added Yosemite to conditionals controlling

File "{BR}:OF:OFSources:Bus:HEATHROW.of"; Line 73 # [2246007] Added include of Burgundy driver on

File "{BR}:OF:OFSources:Bus:HEATHROW.of"; Line 730 # F[ Fdefined? FOR-YOSEMITE 0= F] [if]

File "{BR}:OF:OFSources:Bus:HEATHROW.of"; Line 89 # Make sure all CPUs, not just Wallstreet, have a

File "{BR}:OF:OFSources:Common:BOOTPATH-SEARCH.of"; Line 100 # Flatten and simplify "DoXXX" routines; rev

File "{BR}:OF:OFSources:Common:BOOTPATH-SEARCH.of"; Line 101 # New client call TestPathBoot to do bootinfo

File "{BR}:OF:OFSources:Common:BOOTPATH-SEARCH.of"; Line 106 # Remove string compression services (SCS)

File "{BR}:OF:OFSources:Common:BOOTPATH-SEARCH.of"; Line 109 # TestPathCategory is of the class of time-

File "{BR}:OF:OFSources:Common:BOOTPATH-SEARCH.of"; Line 119 # Enhance ValidPath to translate specially

File "{BR}:OF:OFSources:Common:BOOTPATH-SEARCH.of"; Line 128 # Add facility to nudge around the order of

File "{BR}:OF:OFSources:Common:BOOTPATH-SEARCH.of"; Line 133 # JWH spotted a bug: "line#" is a value, not

File "{BR}:OF:OFSources:Common:BOOTPATH-SEARCH.of"; Line 135 # Change demo test of ValidPath for ide->ata

File "{BR}:OF:OFSources:Common:BOOTPATH-SEARCH.of"; Line 136 # Fixed typo inside debug conditional

File "{BR}:OF:OFSources:Common:BOOTPATH-SEARCH.of"; Line 137 # Add ability for ValidPath to take no

File "{BR}:OF:OFSources:Common:BOOTPATH-SEARCH.of"; Line 141 # Add the ability for ValidPath to ignore

File "{BR}:OF:OFSources:Common:BOOTPATH-SEARCH.of"; Line 143 # Prepare for str compression with "SCS"

File "{BR}:OF:OFSources:Common:BOOTPATH-SEARCH.of"; Line 145 # [2246759] Changed HardCensor to ignore

File "{BR}:OF:OFSources:Common:BOOTPATH-SEARCH.of"; Line 145 # New API call ValidPath, which takes as

File "{BR}:OF:OFSources:Common:BOOTPATH-SEARCH.of"; Line 154 # Flesh out scsi vs. scsi-2 id enumeration

File "{BR}:OF:OFSources:Common:BOOTPATH-SEARCH.of"; Line 159 # Make TestPathCategory do I/O always (see

File "{BR}:OF:OFSources:Common:BOOTPATH-SEARCH.of"; Line 165 # PMValid? no longer requires pmPartStatus

File "{BR}:OF:OFSources:Common:BOOTPATH-SEARCH.of"; Line 167 # Improve internal routine AliasToPath to

File "{BR}:OF:OFSources:Common:BOOTPATH-SEARCH.of"; Line 173 # Change TestPathCategory implementation to

File "{BR}:OF:OFSources:Common:BOOTPATH-SEARCH.of"; Line 93 # Honor "wide" property if set in SCSI

File "{BR}:OF:OFSources:Common:BOOTPATH-SEARCH.of"; Line 98 # Debug mesg now at runtime if AAPL,debug-

File "{BR}:OF:OFSources:Common:DEVICE-TREE.of"; Line 137 # Add implementation of (FINISH-DEVICE-TREE)

File "{BR}:OF:OFSources:Common:DISK-LABEL.of"; Line 26 # Pass "eject" method calls up to parent.

File "{BR}:OF:OFSources:Common:DISK-LABEL.of"; Line 27 # Added NULL string protection around a call to

File "{BR}:OF:OFSources:Common:DISK-LABEL.of"; Line 31 # Disabled debug text output.

File "{BR}:OF:OFSources:Common:HOST-PCI.of"; Line 325 # F[ Fdefined? FOR-YOSEMITE F] [if

File "{BR}:OF:OFSources:Common:HOST-PCI.of"; Line 38 # Fixed uncommented out comments. It looks like BBS

File "{BR}:OF:OFSources:Common:LOADER.of"; Line 46 # When generating the /chosen properies, the form

File "{BR}:OF:OFSources:Common:LOADER.of"; Line 51 # In (INIT-PROGRAM), just before a THROW exit due to

File "{BR}:OF:OFSources:Common:MAC-FILES.of"; Line 26 # Increase safety of volume name detect against

File "{BR}:OF:OFSources:Common:MAC-FILES.of"; Line 28 # Make volume name buffer per-instance.

File "{BR}:OF:OFSources:Common:MAC-FILES.of"; Line 29 # Add method "GET-VOL" to get the volume name and

File "{BR}:OF:OFSources:Common:MAC-PARTS.of"; Line 25 # Set OF global "chosen-partition" if we are given

File "{BR}:OF:OFSources:Common:MAC-PARTS.of"; Line 28 # Pass "eject" method calls up to parent

File "{BR}:OF:OFSources:Common:MAC-PARTS.of"; Line 29 # Part-valid? no longer requires pmPartStatus bits

File "{BR}:OF:OFSources:Common:MAC-PARTS.of"; Line 31 # Fix bug in LOAD stub

File "{BR}:OF:OFSources:Common:MAC-PARTS.of"; Line 32 # Add implementation of LOAD stub

File "{BR}:OF:OFSources:Common:MAC-PARTS.of"; Line 33 # Change partition matching policy to match on

File "{BR}:OF:OFSources:Common:MULTI-BOOT.of"; Line 107 # Add eject of ZIP if mouse button is down. What

File "{BR}:OF:OFSources:Common:MULTI-BOOT.of"; Line 118 # Make work CMD-OPT-SHIFT-DEL. It will now skip

File "{BR}:OF:OFSources:Common:MULTI-BOOT.of"; Line 93 # Change to <BR33> for anti-confusion; no

File "{BR}:OF:OFSources:Common:MULTI-BOOT.of"; Line 95 # Add ability for screen graphics routines to not

File "{BR}:OF:OFSources:Common:PCI-PCI.of"; Line 28 # If NVRAM use-generic? is FALSE then name all pci-

File "{BR}:OF:OFSources:Common:ROM-NODE.of"; Line 40 # Change "model" in /rom/boot-rom to output major

File "{BR}:OF:OFSources:Common:ROM-NODE.of"; Line 44 # Change period back to space, since software like

File "{BR}:OF:OFSources:Common:ROM-NODE.of"; Line 46 # Change from space (" ") to period (".") the char

File "{BR}:OF:OFSources:Common:ROM-NODE.of"; Line 77 # Add Yosemite name to sign-on

File "{BR}:OF:OFSources:IO:ATA-DISK.of"; Line 30 # Comment out a debug printout

File "{BR}:OF:OFSources:IO:ATA-DISK.of"; Line 38 # Change implementation of LOAD from stub to call-thru

File "{BR}:OF:OFSources:IO:ATA-DISK.of"; Line 40 # Call int-off-ata-bus right after reset-ata-bus during

File "{BR}:OF:OFSources:IO:ATAPI-DISK.of"; Line 45 # Add 60ms delay at beginning of OPEN, based on

File "{BR}:OF:OFSources:IO:ATAPI-DISK.of"; Line 51 # Add "eject" method so eject command line will

File "{BR}:OF:OFSources:IO:ATAPI-DISK.of"; Line 53 # [2268963] In OPEN, do obtain-device-info call

File "{BR}:OF:OFSources:IO:ATAPI-DISK.of"; Line 58 # The ZIP drives that go with portables declare

File "{BR}:OF:OFSources:IO:ATAPI-DISK.of"; Line 61 # Make ZIP drives work; more accurate category /

File "{BR}:OF:OFSources:IO:ATAPI-DISK.of"; Line 75 # Add missing call-thru implementation of LOAD

File "{BR}:OF:OFSources:IO:ATAPI-DISK.of"; Line 76 # No longer exit early out of Open as soon as we

File "{BR}:OF:OFSources:IO:ATAPI-DISK.of"; Line 82 # Fix theoretical bug in last checkin

File "{BR}:OF:OFSources:IO:ATAPI-DISK.of"; Line 83 # Support the setting of open-dev-error to indicate

File "{BR}:OF:OFSources:IO:ATAPI-DISK.of"; Line 85 # Call int-off-atapi-bus right after reset-atapi-bus

File "{BR}:OF:OFSources:IO:BMAC.of"; Line 51 # Add "category" property that further identifies broad

File "{BR}:OF:OFSources:IO:BMAC.of"; Line 89 # Add "removable" property to this driver. This property

File "{BR}:OF:OFSources:IO:BURGANDY.of"; Line 28 # [2246758] Changed device-id to 4 on Yosemite

File "{BR}:OF:OFSources:IO:BURGANDY.of"; Line 46 # F[ Fdefined? FOR-YOSEMITE F] [if]

File "{BR}:OF:OFSources:IO:FIREWIRE-NODE.of"; Line 25 # Created. Currently the code herein does nothing

File "{BR}:OF:OFSources:IO:HEATHROW-IDE.of"; Line 101 # Add "removable" property to the "disk" node if

File "{BR}:OF:OFSources:IO:HEATHROW-IDE.of"; Line 106 # Fix hanging bug if trying to open a nonexistent

File "{BR}:OF:OFSources:IO:HEATHROW-IDE.of"; Line 42 # DVD-RAM fix found by Jim Huffman. Add timeout-

File "{BR}:OF:OFSources:IO:HEATHROW-IDE.of"; Line 49 # Change "ide" to "ata-3" for the NAME ONLY

File "{BR}:OF:OFSources:IO:HEATHROW-IDE.of"; Line 54 # Remove setting of properties for ATAPI cas

File "{BR}:OF:OFSources:IO:HEATHROW-IDE.of"; Line 56 # Add "category" property that further identifies

File "{BR}:OF:OFSources:IO:HEATHROW-IDE.of"; Line 66 # Fix bug 2242091: Make DVD (not just CD) ATAP

File "{BR}:OF:OFSources:IO:HEATHROW-IDE.of"; Line 77 # Call Bus:Heathrow.of::ata-enable only once per

File "{BR}:OF:OFSources:IO:HEATHROW-IDE.of"; Line 89 # Register a quiesce word to be called upon OF

File "{BR}:OF:OFSources:IO:HEATHROW-IDE.of"; Line 96 # Make reset-ata-bus leave the nIEN bit so that

File "{BR}:OF:OFSources:IO:IDE-CDROM.of"; Line 24 # Add "category" property that further identifies broad

File "{BR}:OF:OFSources:IO:IDE-DISK.of"; Line 26 # Near the begin of the ide-identify-drive routine, the

File "{BR}:OF:OFSources:IO:IDE-DISK.of"; Line 31 # Do a SRST during CLOSE, so that MacOS's AIM drivers do

File "{BR}:OF:OFSources:IO:IDE-DISK.of"; Line 34 # Boost a 100msec timeout to the up-to-30sec spinup

File "{BR}:OF:OFSources:IO:IDE-DISK.of"; Line 44 # Add "category" property that further identifies broad

File "{BR}:OF:OFSources:IO:IDE-NODE.of"; Line 28 # DAC Added BBS header for Yosemite

File "{BR}:OF:OFSources:IO:IDE-NODE.of"; Line 29 # BAK Fix Maxtor HD drives not being bootable on power

File "{BR}:OF:OFSources:IO:IDE-NODE.of"; Line 39 # Change "ide" to "ata-4" for the NAME ONLY. According

File "{BR}:OF:OFSources:IO:IDE-PCI.of"; Line 29 # Since MY-MAP-IN is called by IDE-QUIESCE outside of

File "{BR}:OF:OFSources:IO:IDE-PCI.of"; Line 35 # Change IDE-QUIESCE routine that is called when OF shuts

File "{BR}:OF:OFSources:IO:IDE-PCI.of"; Line 39 # Change "pci-ide" to "pci-ata" for the NAME ONLY.

File "{BR}:OF:OFSources:IO:SCSI-DISK.of"; Line 33 # Add "category" property that further identifies broad

File "{BR}:OF:OFSources:IO:SCSI-TAPE.of"; Line 26 # Add "category" property that further identifies broad

File "{BR}:OF:OFSources:IO:SWIM3.of"; Line 35 # Add "category" property that further identifies broad type

File "{BR}:OF:OFSources:IO:SWIM3.of"; Line 52 # Add "removable" property to the "disk" node.

File "{BR}:OF:OFSources:IO:USB-HID-CLASS.of"; Line 41 # Make GET-EVENT method support -1 input parameter

File "{BR}:OF:OFSources:IO:USB-OPENHCI.of"; Line 100 # Fix Yosemite (and other projects?) USB keyboards

File "{BR}:OF:OFSources:IO:USB-OPENHCI.of"; Line 120 # Removed setting of power control bits in set-

File "{BR}:RTAS:dispatch.c"; Line 39 # Add a hardcoded SCC serial port address for Yosemite

File "{BR}:RTAS:ev_power.c"; Line 31 # Add conditional compile case for Yosemite

File "{BR}:RTAS:heathrow.c"; Line 28 # [2247583] Changed find_nvram_partition to handle cases where

File "{BR}:RTAS:ioports.c"; Line 31 # Blindly add conditional compile case for Yosemite (call to

File "{BR}:RTAS:mpc106.c"; Line 38 # Add a hardcoded SCC serial port address for Yosemite; same as

S.6. Considerations, Risks, and Assumptions

Even though machine-specific code is conditionally compiled, located in separate files, etc, there are still assumptions in various places about specific hardware implementations in a seemingly-general purpose file. Some known examples:

KERNEL.fas:"I/O Base Address for later use" and surrounding code assumes a Grackle in Mode B architecture.
xxx

S.6.1. Installation

??????

S.6.2. Performance

??????

S.6.3. Tradeoff Decisions

??????

S.6.4. Alternative Designs

??????

S.6.5. Feature Limitations

S.6.5.1. RAID booting

see section below.

S.6.6. Known Design and Implementation Limitations and Risks

None of these should cause problems, but they should be tested for:

x.x.x Address (implies syntax) for the main (Grackle/MPC106) PCI contoller.

With all shipping versions of Yosemite, the path of the main PCI controller is "/pci@80000000". However, with current top-of-trunk sources, and possibly in future Yosemite or other-than-Yosemite machines, the address is missing, as in "/pci".

Simply "/pci" is more correct and preferable, but caused problems with OS-level 3rd party drives which activated themselves only if their device's path with "80000000" existed in the name registry (see also the discussion about generic names).

S.6.7. OEM Impact and Considerations

S.6.7.1. BootPath-Search performance

talk about a performance limitation with many BPS bootable 3rd party cards+chassis explosion

compatible and removable properties

S.6.8. Speed Performance

problems with dec bridge before pci slots

A few data througput performance changes were made which are affected by the PCI Config Space registers "Latency Timer" and "Cache Line Size". These registers are not implemented as writable by all PCI devices.

The Latency Timer, aka "Time Slice", setting specifies the amount of time in PCI cycles that a device can keep hold of the bus (if it is not doing a transaction??????). The Cache Line Size setting ensures coherency if the memory target is mapped into cachable space. See PCI documentation for details.

The following settings shipped with the first release of the Yosemite BootROM. These settings, along with some bugs in the OS, particularly in the "Mac OS ROM" file and pre-2.0 FireWire MacOS software, caused problems for serious video editing users:

Yosemite 1.0 (MacWorld GM) Default PCI Config Settings

	MPC106 Grackle	DEC 21154 Bridge	TSB12V21A FireWire	All Others, such as Slots / Bridges
Latency Timer	`0x00`	`0x20`	`0x20`	`0x20`
Cache Line Size	`0x08`	`0x00`	`0x08`	`0x08`

Along with the aforementioned bug fixes, the following data-throughput-related PCI config settings are in effect for Yosemite starting with the 1.1 (specifically, 1.1f4) BootROM release around May 1999; this is a requirement for serious video editing users (for example, see www.media100.com):

Yosemite 1.1 (QuickTurn) Default PCI Config Settings

	MPC106 Grackle	DEC 21154 MLB Bridge	TSB12V21A FireWire	All Others, such as Slots / Bridges
Latency Timer	`0x00`	`0x40`	`0x10`	`0x10`
Cache Line Size	`0x08`	`0x00`	`0x20`	`0x08`

Note 1: Note again that not all of these registers or bits within a register are supported by all devices; in particular, the Cache Line Size may read as 0x00 for many devices even though we set it to nonzero by default.

Note 2: The default settings for slots can be overridden by FCODE in expansion ROMs on cards, or even later or by an OS driver.

Note 3: There was an earlier policy to set different settings yet for non-motherboard (PCI slot plug-in) PCI-PCI or PCI-Other Bridges, as distinguished from both non-Bridge PCI slot devices and the main logic board (MLB) PCI-PCI Bridge. The version set for the 1.1f5 release does not contain HOST-PCI.of,39a1 which contains this revision, so this aforementioned policy seems to have been decided against.

In order to display these values, go into the OF User Interface, type "dev xxxx" to the node in question, type ".properties", look at the first entry of the "reg" property, type that number, followed by a space and the ".cregs" command. The Latency Timer setting is at offset 0x0d and the Cache Line Size is at offset 0x0c.

For experimentation, it is possible to type "pciaddr longvalue do-config-l!" to modify the setting; remember that the device may not implement some or all bits in the register; example: "newvalue pci config space start from reg property h# 0c + do-config-l!"

S.6.9. Footprints

S.6.9.1. RAM Footprint

There is not RAM footprint per se for the non-OF parts of the Boot ROM, however, after those parts -- Boot Block, MiniNub, Hardware Init -- have run, the compressed OF image that is contained in the Boot ROM is uncompressed and stored into RAM for execution. Furthermore, once OF is running, it uses additional RAM for its memory world.

S.6.9.2. Disk Footprint

There is no disk footprint per se for the Boot ROM, however, for the purposes of updating it may be useful to know what the sizes are. Of the files output in the directory BuildResults by a build without any debugging options turned on, the file "BootROMYosemite" is of course always a fixed size, but the other files can vary in length.

Except the "BootROMYosemite" image file, disk foot print does not equal ROM footprint, because file contents contain flash code wrappers and the BootROM image payload is compressed.

Neither does disk footprint indicate RAM footprint, because the Boot Block, MiniNub, and Hardware Init run out of ROM, and so use no RAM, but OF is uncompressed and placed into RAM for execution.

Disk Footprints (Shipping Conditional Compile Options; Unofficial)

VersionSet	File from BuildResults	Size
`Yosemite_GM`	`BootROMYosemite`	1,048,576 (1M) (decimal) bytes
`Yosemite_GM`	`Yosemite.ofz`	729,617 (decimal) bytes
`Yosemite_GM`	`Yosemite.fmwr`	740,590 (decimal) bytes
`Yosemite_1.1f4`	`BootROMYosemite`	1,048,576 (1M) (decimal) bytes
`Yosemite_1.1f4`	`Yosemite.ofz`	735,582 (decimal) bytes
`Yosemite_1.1f4`	`Yosemite.fmwr`	741,963 (decimal) bytes

S.7. Open issues and ideas for improvements

S.7.1. Firewire (IEEE 1394) booting

Booting from a Firewire device is possible with the hardware but not implemented in software; a firewire OF filesystem-capable block-level driver, such as those already implemented for the hard disks, CD, etc, would be needed. One is currently being written for future projects by Ron Hochsprung. It is theoretically possible to include such support in a future ROM revision; ie, for a speedbump.

S.7.2. RAID booting

Booting from a collection of drives organized as a RAID (Redundant Array of Independent Disks) is possible with the hardware but not implemented in software. In a RAID configuration, multiple drives function as one logical drive in order to gain speed or reliability improvements.

One major problem is that RAID formats vary according to software manufacturer and user setup. How would OF know how which drives are involved and how the data is organized across those drives? Pre-NewWorld, this was not a problem because the MacOS-in-ROM had enough sophistication to be able to load OS-level API-using, native machine language-runtime, hard disk drivers; and it was (and is) at the hard disk driver level that the RAID translation to multiple drives takes place.

Note that it is only RAID booting that is a problem; RAID arrays function on Yosemite as long as they are not expected to be the boot device.

Proposed solutions include:

A standard data structure (on disk?, in NVRAM?) through which RAID setup software can communicate to OF how the data is organized and then OF would additionally be revved to support this.
A small non-RAID partition on one or more drives, that the OS-level RAID driver software could ignore, containing only an OF RAID driver.

S.7.3. Target mode

The hardware theoretically makes it possible for Yosemite to become a mass storage device "server" to another machine; this is called "target mode". Usually target mode is implemented only on portables, however.

S.7.4. Generic Names

GENERIC-NAME-DEFAULT cond compile setting

/pci node address

/pci@80000000/abc/def vs /pci/abc/def and BPS implications with aliases

S.7.5. ATA Drivers

Both the "Ultra" ("IDE-DISK.of", etc) and "regular" ("HEATHROW-IDE.of", etc) ATA drivers are quite messy.

Because newer, post-Yosemite machines will have Ultra ATA in their resident ASICs (Uni-N, Kihei, Key Largo, etc), the specialized Ultra ATA driver for the CMD 0646U2 controller will no longer be necessary and so no development should be done on it except emergencies. This is especially true because its structure is such that it (incorrectly, according to current policy) dynamically determines drive existence and probe-time; this needs to be made static. Also currently, at open-dev time it runs only the driver it was asked to do; this needs to be made dynamic. See BPS documentation.

However, the "regular" ATA driver is correctly structured and its hardware has a future. However, it is messy and very little real knowledge of the hard reset and soft reset has gone into it; it has been hacked on a lot, not the least by me (Ben Koning). The motley collections of resets that happen during typical use cause degradation in out-of-reset-to-boot performance. However, be advised that this code is extremely fragile (another reason for rewriting it). The person who changes it should first hoard a collection of hard drives and CD-ROMs of as many models as possible and especially those quoted in the checkin comments and bug reports referenced in the checkin comments. Again, the code is very fragile. What makes one drive work causes another one to malfunction or not respond. A solid understanding and cleanup is needed.

S.7.6. General Mass Storage Driver Improvements

The mass storage drivers should be improved and tested to handle multiple simultaneous open's, as architected. This probably does not work currently, especially since the driver has to be able to manage, and keep in a known state, the hardware across multiple incoming requests.

This is important because at open-dev time, a client's services options for that driver / instance are locked. For example, if a client wants to read raw bytes without partitioning or file system interpretation, it must indicate so with its path syntax; it is now unable do switch to file system reads using that instance handle. Currently, the client must close that instance before starting another one (or risk bugs). Thus there is a lot of open-close overhead.

The hard / soft bus reset policy needs to be improved also. The end result should have the following characteristics, many of which are already met by current software:

Bus resets: Hard reset should happen only once, at at most twice: A first time before I/O, and perhaps a second time at Quiesce time before going to the OS; soft resets should similarly be done the correct number of times.
Probe time: There must be no delay at probe-time, no matter what the (connected / disconnected / spinup / no-spinup / DC power connector / jumper / slave present / absent / slave-only / etc) situation. This generally means no I/O polling at probe time.
Static Device Tree Nodes, Dynamic Run Time Binding: The presentation in the Device Tree must be of the form "disk@0" for id-able devices or "disk" for single device on bus. The choice of protocol (ATA, ATAPI) handling within the (ATA, SCSI) bus as well as the device handling within that protocol (CD-ROM, ZIP) must be handled dynmaically and automatically with no change in client pathname syntax.
Properties for BPS: For proper boot search handling, the "category" and "removable" properties must be set by the driver (at open-dev time is ok); see BPS documentation.
Multiple client support: Multiple simultaneous instance handles should be able to be open to a driver.
Auto-Inject wait behavior: This could change in the future with, ie, multiple client support and better reset, but for now, the following is crucial to proper BPS and Multiboot support (see BPS documentation):

Auto-Inject Wait Behavior -- The first time an open-dev is done to a device, its OF driver must try to inject the media, wait for spinup, or whatever is appropriate, only after a serious effort, which can take up to 30 seconds, should (and must) an error be issued. All subsequent times (within that OF session), if there is no media, an error should (and must) be returned immediately.

The fact itself that there can only be a single client of mass storage services at a time may limit some things, but this is less important because OF is so single-threaded anyway and there are no high-level demands that would need this.

GENERAL

Machine-Independent BootROM Engineering Information

G.1. Changing from Large MacOS ROM to Small BootROM

G.1.1. Reasons

Starting with the iMac, a change was made from a relatively large (4MB and growing) non-flashable ROM containing Reset, Diagnostics, Hardware Init, Emulator/Nanokernel, and (most but not all of) the MacOS to a relatively small (1MB and could be 512KB) field-updatable Flash ROM containing Reset, Diagnostics, Hardware Init, and (a compressed image of) Open Firmware.

Some, but not necessarily all, reasons for changing are as follows:

Througout the years, so many updates, bug patches and replacements to the MacOS are disk-loaded anyway during boot; thus:

Making for bad architecture
Adding debugging difficulty
Creating the need for patch mechanisms
Wasting ROM space
Adding engineering workload as changes would often be "rolled" from patches into new ROMs

Cost of ROM used to be less than RAM; this is no longer the case
Speed of ROM used to be faster than RAM; this is no longer the case
Cost of mass (disk) storage used to be at a premium for the size of an OS; this is no longer the case
The OS will not always necessarily be MacOS; an unused MacOS in ROM would be a waste
The runtime separation between Hardware Init and the OS provided by the BootROM allows more interchangability and the RAM-based nature of the OS allows easier debugging

G.1.2. Services Provided

The following are the main services provided by the BootROM:

Reset Vector: Reset and other interrupt handling during the first few seconds; also sleep wakeup handling
Boot and Error Beeps: User confirmation of power and basic computer functionality
Diagnostics Factory Process: STM / EMMO support for board testing
Hardware Init: Setting up very low-level settings such as RAM timing, cache settings, etc
Flash Virus Protection: Locking out against and OS or OF program that would corrupt the BootROM
Debugging: First rudamentary debug services, then OF shell aids in board bringup debugging
OS- and CPU- Agnostic Card Support: In theory, OF's bytecode execution of FCODE on a plug-in card or even probing of the PCI device in the abscene of FCODE would allow the OS to use any PCI card for any Apple or non-Apple, Macintosh or non-Macintosh machine, PowerPC or non-PowerPC CPU; in practice, however, OS drivers are required for user-level functionality
I/O Hardware Address and Interrupt Source Information: OF creates the Device Tree that has enough information for the OS to determine what drivers to load and then for those drivers to operate
OS Searching and Loading: OF provides the same user interface for searching and bootable OS as did previous large ROMs; network booting is now possible; future releases will provide a point-and-click OS Picker
Copyright and Cloning Protection: The RAM-based OS looks for a ROM-based copyright string, which legally a clone could not include; even if they were to create their own compatible BootROM (which, although easier than a big MacOS-in-ROM is still fairly difficult)
RTAS: Primitive routines to access NVRAM, the real-time clock (RTC), and other ultimate machine specific basics; part of the CHRP specification; intended to stay resident with the OS (unlike OF); not used very much and perhaps going away

Note that the data path between the BootROM and the Grackle MPC 106 Memory Controller is only 8-bits; it is a small and slow ROM that runs only for the first few seconds after reset. Note that even before mass storage is involved, we are already running out of RAM (the OF image having been uncompressed from ROM).

G.2. Memory Map During BootROM Execution and I/O Address Information for OS

With regard to memory maps, there are several things to consider:

How code is pysically laid on in the BootROM Flash ROM
How that code is mapped / used by the CPU
What the memory map looks like at OF time
Information passed from OF to OS which tells the OS how to map its memory for I/O devices
What the memory map looks like at OS time (beyond this document's scope)

G.2.1. Memory Map during BootROM Execution

G.2.1.1. BootROM Content Layout

G.2.1.1.1. Without System Configuration Block

With the iMac and Yosemite G3, the BootROM is physically laid out as follows. Some of the pieces are "partitions" or "blocks" because they correspond to lockable ranges in the Flash ROM hardware. Coming out of reset, the ROM is mapped 1-to-1 at a fixed address and execution starts at 0xFFF0.0100.

1MB BootROM Layout (iMac, Yosemite Example)

Offset from Start	Physical Address at Reset time due to Grackle Mode "B"	Description
`+ 0x0.0000`	`0xFFF0.0000`	Start of ROM. We use a 1MB ROM, which thus starts at this address, hard-determined by the Motorola MPC 106 Grackle-4 memory controller. Grackle supports a bigger ROM up to 8MB starting at `0xff80.0000` (8/64-bit) and even bigger (16MB) for 64-bit only.
`+ 0x0.0000 ..` `+ 0x0.00FF`	`0xFFF0.0000`	Part of flash-partition block "Boot Block" the contains some jump vectors, versioning information, and an Apple copyright string which legally prevents cloning.
`+ 0x0.0100 ..` `+ 0x0.2FFF`	`0xFFF0.0100 ..` `0xFFF0.2FFF`	Part of flash-partition block "Boot Block" that contains Reset vector and other vectors; some handling code for those vectors (mainly dispatch); some checksumming and general purpose routines; its main purpose is to branch to `JumpToImage`, which jumps to a platform-specific-makefile-provided `RomImageOffset` from the start of ROM. The makefile code at `BootROMCommon.make:"{BRTargetDir}BootROM{Build}"` actually concatenates the pieces together; since each piece is `org`-ed to be the correct size, the pieces line up in the image, and the code in the image knows the offsets because they are passed in as defines.
`+ 0x0.3000 ..` `+ 0x0.7FFF`	`0xFFF0.3000 ..` `0xFFF0.7FFF`	Part of flash-partition block "Boot Block" that contains code from `Grackle.s`, `Processors.s`, etc, (duplicated in "normal" / "recovery" code below) needed for Boot Block operation.
`+ 0x0.8000 ..` `+ 0x7.FFFF` (Not all used; contents are bottom-aligned to start at lower address)	`0xFFF0.8000 ..` `0xFFF7.FFFF`	"Recovery" flash-partition block. This is identical to the "ROM Image" block but slightly reduced with less features and only supports a default set of environment variable settings.
`+ 0x8.0000 ..` `+ 0xF.FFFF` (Not all used; contents are bottom-aligned to start at lower address)	`0xFFF8.0000 ..` `0xFFFF.FFFF`	"ROM Image" or "normal" flash-partition block. This is where the main, higher-level Hardware Init code runs, which after doing its own things then uncompresses OF into RAM and jumps to the OF interpreter (kernel) entry point with some parameters.
`+ 0xF.FFFF (1MB)`	`0xFFFF.FFFF`	End of ROM.

G.2.1.1.2. With System Configuration Block

With the advent of post-Yosemite machines, an effort to save parts costs has resulted in using the flashable BootROM for the storage of items previously contained in separate hardware. The layout below is identical to the pre-System Configuration Block layout above except the new block.

The System Configuration Block contains data such as NVRAM, the Physical Ethernet (MAC) Address, configuration settings in liu of motherboard jumpers that define the features of the motherboard and parameters of the cache and CPU for upgradability, service, etc; it also allows the reduction of conditional compile code sections.

The System Configuration Block will be programmed once at the factory. If it is corrupted, the system may not boot; resoldering the part or (preferably) using a ROM Override Card will be required for recovery. Certain locations and possibly encrypted formats (not documented herein) will be used for factory diagnostics verification of 3rd party board vendor diagnostics-execution compliance.

1MB BootROM with Config Block Layout (post-Yosemite Example)

Offset from Start	Physical Address at Reset time due to Grackle Mode "B"	Description
`+ 0x0.0000`	`0xFFF0.0000`	Start of ROM. We use a 1MB ROM, which thus starts at this address, hard-determined by the Motorola MPC 106 Grackle-4 memory controller. Grackle supports a bigger ROM up to 8MB starting at `0xff80.0000` (8/64-bit) and even bigger (16MB) for 64-bit only.
`+ 0x0.0000 ..` `+ 0x0.00FF`	`0xFFF0.0000`	Part of flash-partition block "Boot Block" the contains some jump vectors, versioning information, and an Apple copyright string which legally prevents cloning.
`+ 0x0.0100 ..` `+ 0x0.2FFF`	`0xFFF0.0100 ..` `0xFFF0.2FFF`	Part of flash-partition block "Boot Block" that contains Reset vector and other vectors; some handling code for those vectors (mainly dispatch); some checksumming and general purpose routines; its main purpose is to branch to `JumpToImage`, which jumps to a platform-specific-makefile-provided `RomImageOffset` from the start of ROM. The makefile code at `BootROMCommon.make:"{BRTargetDir}BootROM{Build}"` actually concatenates the pieces together; since each piece is `org`-ed to be the correct size, the pieces line up in the image, and the code in the image knows the offsets because they are passed in as defines.
`+ 0x0.3000 ..` `+ 0x0.3EFF`	`0xFFF0.3000 ..` `0xFFF0.3EFF`	Part of flash-partition block "Boot Block" that contains code from `Grackle.s`, `Processors.s`, etc, (duplicated in "normal" / "recovery" code below) needed for Boot Block operation.
`+ 0x0.3F00 ..` `+ 0x0.3FFF`	`0xFFF0.3F00 ..` `0xFFF0.3FFF`	Part of flash-partition block "Boot Block" that is the "System Configuration Block" (see table below for details).
`+ 0x0.4000 ..` `+ 0x0.5FFF`	`0xFFF0.4000 ..` `0xFFF0.5FFF`	NVRAM 0. Two NVRAM areas are alternately programmed each time they are written to; only one is touched at each write request.
`+ 0x0.6000 ..` `+ 0x0.7FFF`	`0xFFF0.6000 ..` `0xFFF0.7FFF`	NVRAM 1.
`+ 0x0.8000 ..` `+ 0x7.FFFF` (Not all used; contents are bottom-aligned to start at lower address)	`0xFFF0.8000 ..` `0xFFF7.FFFF`	"Recovery" flash-partition block. This is identical to the "ROM Image" block but slightly reduced with less features and only supports a default set of environment variable settings.
`+ 0x8.0000 ..` `+ 0xF.FFFF` (Not all used; contents are bottom-aligned to start at lower address)	`0xFFF8.0000 ..` `0xFFFF.FFFF`	"ROM Image" or "normal" flash-partition block. This is where the main, higher-level Hardware Init code runs, which after doing its own things then uncompresses OF into RAM and jumps to the OF interpreter (kernel) entry point with some parameters.
`+ 0xF.FFFF (1MB)`	`0xFFFF.FFFF`	End of ROM.

G.2.1.1.3. System Configuration Block Format

The format of the System Configuration Block itself follows below. Unprogrammed sections are set to 0xFF (the erase value of the flash process) to make it easier for various 3rd parties who handle to board to program their respective values (ie, Ethernet address, diagnostics results, etc).

System Configuration Block Format (post-Yosemite)

Byte Offset	Content / Format	Description
`+ 0x00 .. 0x03`	Standard Apple VERS format (see ResEdit, for example).	Build version.
`+ 0x04 .. 0x07`	Standard Apple build date formatt: an ASCII-ized number in the form of `0x19990203`, for example; not a MacOS "number of seconds since 1904" date.	Build date.
`+ 0x08`	n	Motherboard revision.
`+ 0x09`	Watts; bits `[0:5]` are the value, scaled by bits `[6:7]` as follows: `0b00 = 1`(decimal) `0b01 = 0.1` `0b10 = 0.01` `0b11 = 0.001`	Maximum auxiliary power available; delta of total aux power provided by system minus aux power needed by motherboard devices; used by OS power manager to see if it is safe to turn off PCI card power.
`+ 0x0A .. 0x0B`	`+ 0x0A` bits `[0:3]` = product family: `0b0000` = consumer desktop `0b0001` = consumer powerbook `0b0010` = professional desktop `0b0011` = professional powerbook `0b0100 .. 0b1111` = reserved `+ 0x0A` bits `[4:7]` (high 4 bits), plus `+ 0x0B` bits `[0:1]` (low 2 bits) = product platform, which is a running ID within the spaces described above, so for example SawTooth is "2" because it is the second professional desktop (Yosemite is the first). `+ 0x0B` bits `[2:7]` = CPU product version	Product identifier.
`+ 0x0C`	Bit `[0]` = Wake on LAN support Bit `[1]` = PCI slots available Bit `[2]` = PCI bridge exists Bit `[3]` = Built-in display exists Bit `[4]` = Firewire PHY exists Bit `[5:7]` = Sound architecture: `0b000` = Burgundy `0b001` = Screamer `0b010` = IIS `0b011 .. 0b111` = reserved	Feature flags.
`+ 0x0D`	Bit `[0]` = On-board processor Bit `[1]` = IVAD exists (video deflection) Bit `[2]` = Ultra66 available Bit `[3]` = USB switched (in Apple ASIC) Bit `[4]` = Gigabit ethernet PHY exists Bit `[5]` = Registered CKE Bit `[6]` = Hibernation mode Bit `[7]` = Reserved	Feature flags.
`+ 0x0E`	Reserved.	Reserved.
`+ 0x0F`	Reserved.	Reserved.
`+ 0x10 .. 0x13`	Hz	Bus clock speed.
`+ 0x14 .. 0x17`	Hz	PCI 0 clock speed.
`+ 0x18 .. 0x1B`	Hz	PCI 1 clock speed.
`+ 0x1C .. 0x1F`	Hz	PCI 2 clock speed.
`+ 0x20`	???	Processor Info section start; Processor Info signature.
`+ 0x21`	n	Processor Info section bytes used.
`+ 0x22`	2^n	Size of EEPROM.
`+ 0x23`	`0x01` = this version	EEPROM version.
`+ 0x24 .. 0x2B`	ASCII string; 8-char big-endian (left to right = low to high address).	Apple part number, including revision, such as "820-1234-A:, "AP2240-01", etc, encoded as-is with punctuation removed.
`+ 0x2C .. 0x2F`	ASCII string stock ticker; 4-char big-endian (left to right = low to high address).	CPU module manufacturer.
`+ 0x30`	n	Number of processors.
`+ 0x31`	mV	Processor core voltage tolerance.
`+ 0x32 .. 0x33`	mV	Processor core voltage.
`+ 0x34 .. 0x37`	Hz	Processor speed (nominal).
`+ 0x38 .. 0x3B`	ASCII string stock ticker;4-char big-endian (left to right = low to high address).	Processor manufacturer.
`+ 0x3C .. 0x3F`	x	Default `HID0` register.
`+ 0x40 .. 0x43`	x	Default `MSSCR0` (max/V'ger).
`+ 0x44 .. 0x47`	Reserved	Reserved.
`+ 0x48`	Bits `[0:3]` = numerator Bits `[4:7]` = denominator All ratios are with respect to processor speed; actual speed = (processor speed / (numerator / denominator))	Bus / Processor ratio.
`+ 0x49`	Bit `[0]` = parity: `0b0` = unsupported `0b1` = supported Bit `[1]` = reserved Bits `[2:3]` = bus mode: `0b00` = 60x mode `0b01` = MAX mode `0b10` = reserved `0b11` = reserved Bits `[4:7]` = 2^n width	Bus mode.
`+ 0x4A .. 0x4B`	mV	Bus interface voltage.
`+ 0x4C`	n	Number of level-2 (L2) caches.
`+ 0x4D`	2^n	Size of L2 cache. ??? total or individual to be * num ????
`+ 0x4E`	2^n	L2 bus width.
`+ 0x4F`	n	Number of SRAMs per L2.
`+ 0x50`	Same encoding as Bus / Processor ratio.	L2 / Processor ratio.
`+ 0x51`	Bit `[0]` = parity: `0b0` = unsupported `0b1` = supported Bit `[1]` = reserved Bits `[2:3]` = output hold: `0b00` = 0.5 ns `0b01` = 1.0 ns `0b10` = more `0b11` = even more Bits `[4:7]` = SRAM type: `0b0000` = flow through `0b0001` = pipeline burst `0b0010` = late write `0b0011` = 2x data rate `0b0100` = pipeline bust 3 `0b0101` .. `0b1111` = reserved	L2 mode.
`+ 0x52`	mV	L2 interface voltage.
`+ 0x54 .. 0x57`	ASCII string stock ticker;4-char big-endian (left to right = low to high address).	L2 cache SRAM manufacturer.
`+ 0x58 .. 0x5B`	Reserved.	Reserved.
`+ 0x5C`	n	Number of level-3 (L3) caches.
`+ 0x5D`	2^n	Size of L3 cache. ??? total or individual to be * num ????
`+ 0x5E`	2^n	L3 bus width.
`+ 0x5F`	n	Number of SRAMs per L3.
`+ 0x60`	Same encoding as Bus / Processor ratio.	L3 / Processor ratio.
`+ 0x61`	Same encoding as L2 mode.	L3 mode.
`+ 0x62 .. 0x63`	mV	L3 interface voltage.
`+ 0x64 .. 0x67`	ASCII string stock ticker;4-char big-endian (left to right = low to high address).	L3 Cache SRAM manufacturer.
`+ 0x68 .. 0x6B`	Reserved	Reserved.
`+ 0x6C`	x	Memory type.
`+ 0x6D`	n	Number of RAM row addresses.
`+ 0x6E`	n	Number of RAM column addresses.
`+ 0x6F`	n	Number of banks on SDRAM devices.
`+ 0x70`	`tCL`	CAS latency (`tCL`).
`+ 0x71`	`tRCD`	RAS to CAS delay (`tRCD`).
`+ 0x72`	`tRP`	Row (bank) precharge time (`tRP`).
`+ 0x73`	`tRAS`	Precharge time to RAS latency (`tRAS`).
`+ 0x74`	`tCCD`	CAS to CAS delay (`tCCD`).
`+ 0x75`	`tDPL`	Data-in to precharge latency (`tDPL`).
`+ 0x76`	x	SDRAM attributes such as registered, buffered.
`+ 0x77`	ESDRAM = `0x01`	Superset technology.
`+ 0x78`	n	Number of soldered memory controller banks.
`+ 0x79`	n	SODIMM bank numbers such as 0, 1.
`+ 0x7A`	Reserved	Reserved.
`+ 0x7B`	Reserved	Reserved.
`+ 0x7C .. 0x7F`	??? format ???	Checksum ??? covers what ??? what format ???
`+ 0x80`	`0xEA`	Ethernet address signature.
`+ 0x81 .. 0x86`	x	Ethernet address.
`+ 0x87`	??? format ???	Ethernet address checksum.
`+ 0x88 .. 0xFF`	Classified	Configuration Test Data section for diagnostics and 3rd party manufacturing compliance enforcement.

G.2.1.2. BootROM Execution Memory Map at Hardware Init Time

The memory map can vary by machine. However, for NewWorld architecture machines recently, there has not been too much variation at the gross level, so we include it here.

Memory Map at Hardware Init Time (Yosemite Example)

Virtual Address	Physical Address	Description
`0x0020.0000` (2MB)	`0x0020.0000` (2MB)	OF / RTAS image and initial OF kernel init execution. OF then resets MMU setup (modifies BAT (block address translation) regisisters) to map its virtual addresses to the `0xFF80xxxx` range. Note this assumes a minimum amount of RAM; address defined in `HardwareInit.s:"kRAMOpenFirmware"`.
`0xFFF0.0000`	`0xFFF0.0000`	Start of ROM as per Grackle MPC 106 Address Map "B" Setting (see Motorola MPC 106 book, chapter 3). Contains some jump vectors, versioning information, and an Apple copyright string which legally prevents cloning.
`0xFFF0.0100`	`0xFFF0.0100` (no vm)	Reset vector. Code starts executing from this location (as opposed to this address containing a pointer). See `POST:BootBlock.s`. See Hardware Init sequence description.
`0xFFF0.0200 .. 0xFFF0.3000`	`0xFFF0.0200 ...`	All of the other PPC interrupt vectors. All interrupt handlers branch to the same code at `ExceptionHandler_Common`.
	`0xFEC0.0000,` `0xFEE0.0000`	Grackle MPC 106 gateway to PCI space; these are only two registers (!) (all addresses in their range are aliased) for address/data to do a read or write PCI config cycle.
`0xF300.0000`	`0xF300.0000`	Paddington Apple I/O ASIC. This is an example of the I/O space starting at `0x8000.0000` and ending at `0xFCFF.FFFF` in Address Map "B". Like other PCI devices, Paddington can be assigned to any physical address for CPU access, but is set to `0x80800000` by means of an arbitrary constant in `GRACKLE.of` "to boot NT, just in case" (plus that address is probably a MacOS requirement at the present time).
Not always mapped	`0x8000.0000`	Start of I/O space as per Grackle MPC 106 Address Map "B" setting.

`0x0010.0000` (1MB)	`0x0010.0000` (1MB)	L2 cache test area used by Hardware Init and data stucture passed to OF kernel init (ptr in register `r3`).
`0x0000.0000`	`0x0000.0000`	Start of RAM. ?????Contains MacOS sleep wakeup vector.

G.2.1.3. BootROM Execution Memory Map at OF Time

When OF gets control, part of its kernel initialization is to rearrange the memory map by programming the CPU's Block Address Translation (BAT) registers (when the OS gets control, it will then also rearrange it to its final state). The resulting memory map is as follows. As stated above, the memory map can vary by machine but there has not been too much variation at the gross level recently, so we include it here.

Memory Map at OF Time (Yosemite Example)

Virtual Address	Physical Address	Description
`0xFF80.0000 ??????`	`0x0020.0000` (2MB)	OF / RTAS image and initial OF kernel init execution. OF then resets MMU setup (modifies BAT (block address translation) regisisters) to map its virtual addresses to the `0xFF80xxxx` range. Note this assumes a minimum amount of RAM; address defined in `HardwareInit.s:"kRAMOpenFirmware"`.
`0xFFF0.0000`	`0xFFF0.0000`	Start of ROM as per Grackle MPC 106 Address Map "B" Setting (see Motorola MPC 106 book, chapter 3). Contains some jump vectors, versioning information, and an Apple copyright string which legally prevents cloning.
`0xFFF0.0100`	`0xFFF0.0100` (no vm)	Reset vector. Code starts executing from this location (as opposed to this address containing a pointer). See `POST:BootBlock.s`. See Hardware Init sequence description.
`0xFFF0.0200 .. 0xFFF0.3000`	`0xFFF0.0200 ...`	All of the other PPC interrupt vectors. All interrupt handlers branch to the same code at `ExceptionHandler_Common`.
???? where is this mapped; that is, how does OF do "config-l!", etc???????	`0xFEC0.0000,` `0xFEE0.0000`	Grackle MPC 106 gateway to PCI space; these are only two registers (!) (all addresses in their range are aliased) for address/data to do a read or write PCI config cycle.
`0x8080.0000`	`0x8080.0000`	Paddington Apple I/O ASIC. This is an example of the I/O space starting at `0x8000.0000` and ending at `0xFCFF.FFFF` in Address Map "B". Like other PCI devices, Paddington can be assigned to any physical address for CPU access, but is set to `0x80800000` by means of an arbitrary constant in `GRACKLE.of` "to boot NT, just in case" (plus that address is probably a MacOS requirement at the present time).
Not always mapped	`0x8000.0000`	Start of I/O space as per Grackle MPC 106 Address Map "B" setting.
`0x0010.0000` (1MB)	`0x0010.0000` (1MB)	Data stucture passed to OF kernel init (ptr in register `r3`).
`0x0000.0000`	`0x0000.0000`

G.2.2. I/O Device Memory Map Layout Creation for OS with "assigned-addresses" Properties

The PCI devices can be programmed, by means of PCI Configuration Space writes, to decode and respond to any physical address requested by a software access from the CPU.

The programming of all PCI devices' configuration space registers, and thus all PCI device placement in the (physical address) hardware memory map, is done by OF at probe time. The information on where devices are so mapped is communicated to the OS by the "assigned-addresses" properties that are generated by OF as the devices are programmed.

In reality, the OS may also ignore such properties and assume that certain hardware is at certain addresses, and the OS's Trampoline Code generates its own "AAPL,address" and other properties. Also, we are only referring to physical addresses; virtual addresses may be different and are assigned by the OS's mapping, ???????established in the Nanokernel (but note that software must still be able to know physical addresses; ie, when a driver is programming a DMA engine; there are OS calls to do this).

A card can request space in the computer's physical address memory map for its registers (its real, functional registers, not its configuration space registers) by declaring, in the card FCODE or motherboard node FCODE, a "reg" property. The format of this property, as well as that of assigned-addresses, ranges, etc, is described in the PCI Bus Binding document. Alternatively, a motherboard device will have "its" FCODE as part of the motherboard OF code and will similarly declare a reg property. If there is no FCODE, the configuration space registers 0x10..0x30 are probed by a all-1's write and read; the hardware responds with the size (and type, indicated by the low 2 bits) required.

The reg property from probe-time FCODE execution or register probe is a request to OF to allocate memory for OF purposes (OS will overwrite), map memory for OF purposes (OS will overwrite), create "assigned-addresses" for OS purposes, and add to a list intended for addition to properties for the parent bridge.

In HOST-PCI.of, PROBE-PCI-DEVICE calls PROBE-ALLOC which does the CLAIM-REAL OF memory allocation, and then calls NEW-ASSIGNED-ADDRESS adds to PCIARQ list. After probing the devices in that node, the sizes required are generated and programmed by (ALLOCATE-ADDRESSES); then the list is then unraveled by (MAKE-ASSIGNED-ADDRESSES) which calls MAKE-"ASSIGNED-ADDRESSES" to create the assigned-addresses properties.

G.2.3. Interrupt Map Layout Creation for OS with "interrupts", etc, Properties

Information regarding interrupt sources is communicated to the OS via the Device Tree by means of nodes that contain "interrupts" properties. The presence of such a property indicates that the node's device hardware is capable of asserting an interrupt request.

The contents of an "interrupts" property only refers to PCI interrupts and not CPU interrupt(s). ????IS THIS TRUE, WITH VALUES LIKE 0x0f 0x04 0x05 for SCCA???????

An additional "interrupt-parent" property contains the phandle of the node that ?????????. In practice, all nodes that declare such properties point to only one: The "interrupt controller" node in "mac-io".

The "interrupt-map" and "interrupt-map-mask" properties, defined in FINISH-DEVICE-TREE.of do something else to tell os about int src ???????

???????HAVE SOMEONE CHECK THE ENTIRE SECTION "G.2". IS IT ALL CORRECT????????

G.3. Boot Block and Hardware Init Execution

G.3.1. Sequence Overview

Out of reset at 0xFFF00100 physical and virtual address (no vm yet) in POST:BootBlock.s, 0x100 bytes into the ROM.
If hard reset (power on, reset key) go to HardReset code, else (OF reset-all command, restart from MacOS) go to JumpToImage code.
The HardReset code first which includes a out-of-sleep mode case that jumps through a vector at 0 back to the MacOS world.
The HardReset code initializes processor settings, PCI controller settings, and enough Mac I/O controller settings to do rudamentary things such as sound for error beeps. The ROM is checksummed, locked against viruses attacking Flash ROM, and certain error recovery schemes exist.
The JumpToImage code has a branch to an address provided by the makefile process to the start of higher-level hardware init code and OF; that is, the address of the start of the ROM Image whose code starts in POST: HardWareInit.s:"MainCodeStart"; first instruction is a branch to "HWInitEntry".
The Hardware Init code calls routines that are conditionally included on a per-machine as-needed basis (sort of a recursive-descent include-file and do-something or do-nothing subroutine structure; read POST: HardWareInit.s:"This is a shell" for details and prior to adding something new).
The Hardware Init code initializes all sorts of very basic things such as RAM and Cache settings. At some point, the Boot Beep is played. Factory diagnostics gets to run, etc. Eventually Open Firmware is entered.
Open Firmware is run by Hardware Init by first LZSS-decompressing its image into a section in RAM, and then passing some parameters (clock speed, total RAM, etc) in a struct pointed to by r3. At this point, we are done running out of ROM forever until reset.
Execution, now in RAM, and in the OF Kernel at the beginning setup stuff, continues at OF:OFSources:Kernel:KERNEL.fas:"ROMstartVec". OF will be setting up its own virtual address translation and interrupt handling.

G.3.1.1. Error Detection and Recovery

The following is the user interface of the boot block code. See also the section elsewhere in this document describing at-reset-time key-down commands.

Boot Block User Interface

Direction	Event	Source Code	Action / Description
Input	None	`BootBlock.s:"@boot:"`	Normal boot. Try the "normal" image first, then try the "recovery" image (see longNMI below for reversal of this sequence).
Input	Out of power-up or hard reset, less than 5 seconds of NMI down followed by carriage return serial I/O input on either port at 56/8/N/1.	`BootBlock.s, CheckNMIOverride`	Enter MiniNub, allowing minimal serial I/O debugging (type "help").
Input	Out of power-up, more than 5 seconds of NMI down with no carriage return (CR) serial I/O input on either port.	`CheckNMIOverride,kLongNMI`	Enter "recovery" mode (play long boot beep): Enable Flashing, then try to use "recovery" image first, then "normal" image if that fails; if both fail, hang.
Input	5 seconds of NMI down but no carriage return (CR) serial I/O input on either port.	`CheckNMIOverride, kMininubWaitSeconds`	Enter "recovery" mode; if entered from power up, enables flashing.
`---`	`---`	`---`	`---`
Output	1 long error beep (459Hz sine wave for 2sec)	`BootBlock.s, Sound.s, kErrorRecoveryMode`	Indicate to user that we are in "recovery" mode; caused by holding down NMI at power-up.
Output	1 short error beep (459Hz sine wave for 490ms)	`Grackle.s,FatalNoRamError, kErrorNoRam`	No RAM installed.
Output	2 short error beeps (459Hz sine wave for 490ms, 250ms separator)	`Grackle.s, FatalRamConfigError,kErrorBadRamConfig`	Incompatible RAM types.
Output	3 short error beeps (459Hz sine wave for 490ms, 250ms separator)	`Diagnostics.s,FatalBadRamError, kErrorNoGoodRam`	No good RAM banks.
Output	4 short error beeps (459Hz sine wave for 490ms, 250ms separator)	`BootBlock.s,kErrorBadRom`	No good boot images in the BootROM; "normal" and "recovery" images both checksummed bad, so we hang.

Regarding RAM errors, the routine Grackle.s:"SizeDRAM", described above, calls FatalNoRamError if it finds all DIMM memory slots empty, or FatalRamConfigError if it detects mixed DIMM cards in the memory slots (EDO+SDRAM). The FatalBadRamError happens if all memory banks failed as indiated in NVRAM; however, it is possible that no RAM tests were enabled to run, and in this case, no errors were indictated, and so we continue; however-however, it appears that Diagnostics.s:"SetupDiagNVRAM":"set MemoryTestFlag to force FirstBoot tests" arranges for at least one test to run if NVRAM is corrupt or uninitialized.

After the fatal RAM error beeps are played, the MiniNub is entered; after the bad ROM error beep, we hang.

G.3.1.2. Boot Block and Hardware Init Tasks Performed

This section runs through a time-based sequence of the what kinds of things HardwareInit sets in a bit more detail than the section above.

The description below is typical of post-iMac machines, but Yosemite has been used as an example here, and only a "normal boot" case is followed.

An engineer who is adding support for a new machine, must carefully choose where a new routine should logically go and if necessary add a new source file for a new type of I/O controller "chip" etc; they should read the big comment in HardwareInit.s carefully.

Reset vector and initial dispatch as described in sequence overview above.
BootBlock.s:"HardReset" is entered.
Processors.s:"InitProcessor" is entered, which "Checks if we're running BootEmulator, and simulates as much of a hard reset state as possible. Also, initializes the runtime flags stored in the CR. Initializes the MMU with a default map, enables caches, disables almost everything else. Puts a conservative value in DecClock to allow crude timing services until the real value is determined.". Regarding the MMU, default settings from constants (kDefaultDBAT0U, etc) are put into block address translation (BAT) registers.
Grackle.s:"InitPCIBridges" is entered (Yosemite example), which sets up the behavior of any bridges beyond Grackle as a PCI controller (that is, interface between CPU and PCI). Many config space registers are set, which are documented in the book for the bridge, but several things are worth noting:

This and other routines that control the PCI devices by doing PCI Configuration Space read and write cycles (see PCI specification) do so by two routines Grackle.s:"PCIConfigSpaceReadWord" and "PCIConfigSpaceReadWord". These routines perform their tasks by accessing addresses 0xFEC00000 (PCIConfigAddrReg) and 0xFEE00000 (PCIConfigDataReg); these addresses are hardcoded because they are defined by Grackle being in Address Map "B" mode, which is in turn set by a hardware wiring input.
The fact that a machine (Yosemite example follows) has a secondary bridge plus where that bridge is in PCI space is defined by the Yosemite.s:"ExternalPCIBridgeIDSEL" (0x80006800) equate and its value is used to find it in PCI Config Space.
This routine also sets up access to the Paddington (Macintosh Legacy I/O ASIC) by using the PCI Config Space "pointer" defined by the Yosemite.s:"IOCntrlIDSEL" (0x80012800) equate; it is set to an address defined by Yosemite.s:"IOCtrlBaseAddress" (0xF3000000).

IOControllers.s:"InitIOController" code is entered, which sets up Paddington's Feature Control Register (one of about 3 "main" registers documented at the beginning of the Grand Central/Heathrow/Paddington book, which controls which features are enabled for this machine. Additionally, the following devices are set to rudamentary quiescent but initialized modes:

Its SCC (serial port)
Gateway to CUDA (I2C/RTC/Power control) (simple proprietary "serial" interface to it)
Gateway to Sound ASIC settings

At this point we have perfomed enough initialization that the computer is usable enough for HardwareInit to proceed past boot block stage; we have a working CPU, we nonoptimally have ROM and RAM, we can play error beeps, we can read hardware settings, etc.
The ROM is checksummed and a bitmap of valid/corrupt sections is made. If anything is corrupt or if user keys such as NMI are down, see the section "Error Dectection and Recovery" above for what the code does.
Flash ROM is protected against viruses by means of setting a bit in one of Grackle PCI registers; see Grackle.s:"LockoutFlashWrites". Once that bit is set, only a power cycle (not even hard reset) can re-enable flashing. Since at this point, the boot beep has not even happened yet, there has been zero chance of user program execution; not even OF patches. Perhaps the only way is through a serial port inputted program by means of the MiniNub, but the MiniNub can only be entered with the NMI key down.
HardwareInit.s:"HWInitEntry" code is entered, by means of HardReset to ExceptionHandler_Common to JumpToImage to (BootBlockStart+RomImageOffset), which is "HWInitEntry" with the way things are linked by the BootROMCommon.make makefile using the LayoutImage tool. HWInitEntry has a list of calls, as follows.
Call IOControllers.s:"InitInterruptController", (do not confuse with "InitIOController") which for Yosemite does nothing.
Call PowerMgmtMicro.s:"DownloadPowerMgmtMicro", which, on a Yosemite, does nothing, because the "hasPMU" conditional compile has not been not been set by (does not appear in) Yosemite.s. This is a perfect example of how the build structure works; note that the call and do-nothing blr instruction still exists. This tiny overhead is a neglegible price to pay for neat code organization.
Call IOControllers.s:"CheckSysModuleEEPROM", which uses CUDA (Yosemite and other desktops) or PMU (portables) (or some other method for future machines) to check System Module's signatures/checksum using I2C bus transactions. ????The System Module is the CPU card???--the schematic does seem to have an I2C going to the cpu interposer card.
Call Grackle.s:"GetTimings", which determine Bus/Decrementer/CPU frequencies, based on table lookup and jumper settings.
Call Grackle.s:"InitMemoryController"to improve memory access settings over nonoptimal hardware defaults.

SetupGrackle configs it with the exact processor type and L2 cahce settings.
ConfigROMRegsGrackle overrides default slowest at-Reset ROM timing settings to proper values based on now-known bus speeds; registers ROMFAL and ROMNAL (first and next access latency) are programmed and are also important for Flash write cycles.

Call HardwareInit.s:"CheckNVRAM", which checks NVRAM signatures for only the ones currently defined and also the checksums; if invalid, rebuild entire contents.
Call HardwareInit.s:"CreateDiagNVRAMPartition", which allocates a diags partition, if one does not already exist.
Call Grackle.s:"SizeDRAM"(do not confuse with JoinBanks), which fills out the nvBankNNInfo fields in NVRAM for OF use/OS use. SizeDRAM uses GetBankInfo.
Call HardwareInit.s:"SizeExternalCaches" (do not confuse with EnableExternalCaches), calls Grackle.s:"SizeExternalCaches_Grackle", which sizes and prepare L2/L3 caches (if present), for Yosemite calls GetL2CacheInfo, which gets its info from tables based on processor card settings read from the Paddington ASIC. The information is written into NVRAM for OF use/OS use.
Call Sound.s:"PlayBootBeep", which does everything necessary to play the boot beep. Various sound CODEC hardware implementations are handled, as are issues surrounding volume setting and output device settings and plug-ins (ie, headphone jack, etc). The beep image is decompressed into RAM because it is stored compressed to save space; even so, there is a "shared beep" mechanism to share the data between "normal" and "recovery" post-boot-block code images.
Call Diagnostics.s:"POST", which runs the diagnostic code (memory tests, cache tests, etc) as per NVRAM settings, and results are recorded in NVRAM. Factory application-level code (PowerTest, etc) enables it, collects results, and disables it.
Call Grackle.s:"JoinBanks"(do not confuse with SizeDRAM), which stitches good memory together into a contiguous space, using good-memory bank map previously stored in NVRAM by SizeDRAM (actually, "joining" is something only older machines needed; Yosemite's hardware automatically configures different RAM DIMMs into a contiguous linear space, so the JoinBanks routine is really for any type of memory preparation; in this case, setting timing settings). It calls JoinMemBanksRegs, which reads from NVRAM, and then ConfigRAMRegsGrackle, which writes to Grackle registers configuring it for optimal RAM timing settings, using already-calculated bus speeds as an index into a table of values for each RAM related register setting; multiple tables for multiple machines exist that are conditionally-compiled.
Call HardwareInit.s:"EnableExternalCaches" (do not confuse with SizeExternalCaches), which enables L2 / L3 caches, if present and working, by checking NVRAM and setting CPU spr register bits for L2 and calling Processors.s:"EnableExtL3Cache" (presently does nothing) for L3.
Call Processors.s:"InitOtherProcessors", which would set up a 2nd, 3rd, etc, processor for a multiprocessor system. It presently does nothing; since multiple processors are supported, presumably such initialization takes place later, such as in the NanoKernel?????????
Call HardwareInit.s:"AllocateRamImage", which handles BootEmulator environment; that is, it copies an image of the MacOS ROM into RAM for debugging execution. This is apparently code left over from the MacOS in ROM pre-OF-3 days. It is presently conditionally compiled to do nothing; indeed some of the equates needed are not even in the OF-3 BootROM sources.
Call HardwareInit.s:"CallOpenFirmware", which transfers control to the OF kernel initialization point, passing it a few paramters (see section below); it will not return.

G.3.1.3. Clock / Memory Determination and Calling OF

The OF / RTAS image is stored compressed. It is uncompressed and placed into RAM at the address given as HardwareInit.s:"kRAMOpenFirmware", currently 0x00200000.

Just before Hardware Init jumps into the start of the OF image, never to return, it sets up register r3 to point to a data structure (at kRAMPlatformInfo, currently 0x00100000) with the following fields, based on its calculations or previous knowledge:

piRAMSize -- Total RAM size retrieved by CalculateTotalRAM from NVRAM, which was stored there earlier by SizeDRAM into an NVRAM partition created just before (see HardwareInit.s:"@hardReset" list of calls). Currently, RAM sizes are determined by reading I2C ROMs on the RAM DIMM cards; previously RAM was sized "manually" by a specialized memory test. In the even further past, this was complicated by programmable, initially noncontiguous, RAM banks that had to be "stitched" together by HardwareInit.
piL2code -- L2 cache code, describing L2 cache type. Currently zero.
piCPUclock -- Processor frequency; see below for derivation.
piBUSclock -- RAM bus frequency; see below for derivation.
piPCIclock -- PCI bus frequency; see below for derivation.

The clock speeds are derived from hard settings. A partial Yosemite example is as follows: HardwareInit.s:"GetTimings" -> Grackle.s:"GetTimings_Grackle" -> "GetPCIFrequency" -> (table or CPU bit driven). Everything is usually table driven based on the reading of a register that reads the MLB jumper block settings and CPU bits set by processor daughterboard wirings.

An absolute-address jump then happens to kRAMOpenFirmware.

G.4. OF Compilation and Execution

G.4.1. BootROM OF Image Compilation Process

OF compilation is discussed here first, before the discussion of OF runtime initialization and runtime architecture, because it is not straightforward, and it is helpful to have a general idea of the compilation process prior to following the code execution by looking at source files.

Unlike POST and RTAS, and the rest of Apple OS sources, not all of the source files directly compile into "finished" code that makes it into the BootROM executable: Some of the Forth language files are instead "tools" whose eventual side-effect it is to emit code.

It would have been possible to implement the entire FCODE API natively; that is, each FCODE's execution would trigger machine code that was compiled from assembly or C source text. This is not how Apple's OF implementation works; instead, FCODE words (on a ROM on a card, for example) trigger interpreted FORTH code that runs under a kernel, which in turn was compiled from assembly source text into machine code.

It would have been possible to use a straight PPC assembly language compiler (assembler) to create the machine code image of the OF kernel; instead, a Forth-based assembler is used which is in actuality a FORTH program that runs at build time. Likewise, it would theoretically have been possible to compile the nonkernel parts of OF directly from source text into FORTH code or OF tokens; instead, this too is done by a FORTH program that runs at build time.

G.4.1.1. Execution Model Facts Related to Compilation Process

Forward symbolic references (acessing a routine, variable, etc, that is defined "later") are not allowed. This dictates the sequence of (sometimes nested) source file inclusion somewhat. A workaround for this limitation is the definition of a vector ("defer word") that is first defined and later filled in.

Everything in FORTH is executed. Routine ("word") definitions are compiled upon being encountered at runtime, as are variable definitions. This is one reason why forward symbolic references are not allowed.

Because OF is a FORTH-philosophy-following operating system, everything in OF is executed, and we speak of "probe time" and "user level execution time".

When first encountered, an FCODE token stream is "detokenized" into executable form and run, thus running all code that is not a part of a routine (not part of a "word" = not part of a "colon definition"). This "probe-time" execution of course involves the creation of routines by means of colon definitions, but also involves the creation of variables and data structures. But most importantly, probe time code can generally make use of the same OF services normally available and thus can be "just plain code".

Later, during "user level execution = "runtime", there is another chance for words that were defined at probe time to run, as would normally be the case for a device driver on a PCI card's ROM, for example. User level execution time is after all probing and Device Tree construction is complete; this is why the main source file that finishes the probe and starts off this time is called USER-INTERFACE.of and why it is located in the Kernel source directory.

Groups of words often form an "object" of code; that is, a collection of routines and related data structures that are bound together into a unit ("node"), that contain a public interface and can hide internal symbols, that have a standard API that is identical across all such objects, that have as part of their APIs standard constructor / destructor ("open" / "close") routines that allocate / deallocate memory and other resources and are automatically called by the OF operating system, that tend to have accessor calls for their data structures, that can call up an inheritance chain of also-opened parent nodes / objects, that have a unique, automatic, per-client global variable world and execution context instance, and whose routines can be called by name. About the only object-oriented mechanisms not available are multiple inheritance and easy overriding of default behaviors.

G.4.1.2. OF Source File Types

The code which starts at kRAMOpenFirmware after coming from Hardware Init is compiled from OFSources:Kernel:Kernel.fas. The "fas" suffix stands for Forth Assembler. In fact, the following suffixes are used in the BootROM sources:

BootROM Source File Suffixes

Suffix	Description
`.s`	"Source". Power PC source code, input to the `asmppc` tool, compiled into the BootROM as target code.
`.of`	"Open Firmware". FORTH language source code making use of OF "words" (system calls) or internal routines; "compiled" by the action of the `aforth` tool's execution of "`.fth`" files such as `META-TOKENIZER.fth`; the end product (translation into tokens and internal references) of these "`.of`" files makes it into the BootROM as target code.
`.def`	"Definition". Generally contains lists of definitions resolving symbols to their values or defining sets of defaults. Sometimes generates target code (`NVCONFIG-CHRP.def`); sometimes does not (`FCODES.def`).
`.fth`	"Forth". FORTH language source code that does not compile into target code; these files are executed (rather than compiled) by the `aforth` tool, and the side-effect of their execution is to pick up "`.of`" files and turn them into code that makes it into the BootROM.

G.4.1.3. OF Build Overview

Apple's OF implementation is compiled as follows: A FORTH interpreter (aforth) is invoked during the build process, and it is given files ("meta" compiler files) whose execution has the side effect of emitting the target code.

The FORTH interpreter aforth that is used during the BootROM build process is itself built from sources in the ForthCompiler BBS project entity. It is built only when necessary; ie, if something has changed or the engineer has never built it yet; updates are rare. Its build process is multi-step in its own right: A set of text files is preprocessed by an "M4" macro preprocessor and then compiled to form a primitive FORTH interpreter, which is then in turn fed files to construct the full aforth FORTH interpreter. ???is this correct???should we expand on this summary??????

Unlike the (Yosemite) Hardware Init code, which is compiled by the ppcasm assembler standard MPW tool, the OF Kernel piece of PPC assembly source in OFSources:Kernel:Kernel.fas is compiled by the Forth PPC Assembler. Some non-Yosemite products, such as iMac, have their Hardware Init implementations compiled by the Forth Assembler; the choice is a matter of taste.

As part of the makefile sequence, BBS scripts have already activated the project-specific makefile (ie, Yosemite.make) and makefile execution eventually leads to Make:BootROMCommon.make and its "{BRObjDir}OF" dependency. AForth is given some commands to execute that include setting a constant in the FORTH world (a ROM version, etc), and then to execute (evaluate) the file Yosemite.fth.

Yosemite.fth sets global conditional compile flags, and then FLOADs ("includes") Kernel:META-COMPILER.fth, passing source files THE-TREE.of and THE-FILES.of as parameters. It is the execution (evaluation) of META-COMPILER.fth that causes the OF part of the BootROM to be compiled from source text into target code.

Note, for example, that one of the files META-COMPILER.fth uses is Kernel:asmPowerPC.fth, which contains FORTH words that, when executed by the encountering of mnemonics in a .fas source file, emit the proper hex codes into the output stream.

While doing this, the meta-compiler emits progress reports to the file BuildResults:*:Text:*.log (Yosemite example: Yosemite.log) from the various ".(" print statements seen in META-COMPILER.fth.

G.4.1.4. Activating the "OF Compiler"

META-COMPILER.fth defines words to help it compile and also words that make it into the output target; this is interspersed with the inclusion of other files that make up the whole OF image. In order, this inclusion proceeds as follows:

[Remember that fload is a compile-time aforth source text include; these floads

define words (routines) and data to help the compilation that follows only; they do

not generate any code]

fload ANSI.fth -- ANSI extensions used as conveniences for the OF build.
fload LOWLEVEL.fth -- Register numbers, string compares, more conveniences for the OF build.
fload AsmPowerPC.fth -- PowerPC assembler (machine code-emitting words) for the OF build.
fload FCODES.def -- Translation between IEEE 1275 OF API bytecodes and their official names.

G.4.1.5. OF Part Output from the "Compiler"

Up until this point, no code emitting has happened. Now, starting with the Kernel, code is added to the output file that will eventually be "THE-IMAGE.bin" as performred by the "save-image" command at the end of the Yosemite.fth file, which is renamed by the makefile (BootROMCommon.make) to "OF" after aforth is finished. The "OF" file is then used as input for further link steps (LZSS compression, LayoutImage).

The code is added to the OF "heap" (where the primitive "here" points to; that is compile-time aforth's here, not to be confused by runtime OF's here); all this code is then saved by the last few lines of (for example) Yosemite.fth, which invokes aforth's (save-binary) to save the OF "heap" with all the assembled, included, and tokenized code to the file "THE-IMAGE.bin", which is then picked up by BootROMCommon.make, which invoked aforth with Yosemite.fth in the first place, and renamed and used for further processing-inclusion into the BootROM. ???is this correct????

G.4.1.6. Compiling OF Interpreter / Kernel and Bytecode Executor

The code that begins the formation of code in the OF part of the BootROM comes from the following files; source files that actually contribute to output to ROM will be underlined:

[Remember that fload is a compile-time aforth source text include; these floads

cause the addition of code that goes into the OF image]

fload KERNEL.fas -- Entry point from Hardware Init with a few parameters; reprograms virtual memory world; implements most-basic runtime architecture; implements most-basic system calls that cannot be implemented in FORTH called "primitives" (ie, memory accessors, branches, etc). All code that is not part of the Kernel can be in OF, and so this is the only file whose source text is not in OF / FORTH.
fload BYTE-LOADER.of -- Decoder that reads in bytecode tokens and converts it to an internal executable representation ready for execution "by" the Kernel. All code that is not part of the Byte Loader can be tokenized; since this is more compact, it is preferred, and so this is the only file that is not stored in the BootROM OF image as tokenized FCODE. ???is this -fully- correct???

The code above has been added in "straight", non-tokenized form: the Kernel, of course, has been added in this way because it is machine code, but the byte-loader is so included also because it is involved in interpreting a token stream and converting it into a native Apple FORTH runtime image that is ready for execution by the Kernel, and therefore cannot itself be represented as bytecodes.

The code above starts at, and starts because of, the line "ROMstartVec org". The "org" is ???????????

G.4.1.7. Compiling OF Basic Operating System

At this point -- after kernel and byte-loader compilation -- the Tokenizer in Kernel:META-TOKENIZER.fth is included with an FLOAD; from now on, source text is tokenized; that is, converted from local text references to symbol byte codes and OF "system calls" text references to IEEE 1275 byte codes before inclusion into the output target image. At runtime, this byte steam will be detokenized by code in BYTE-LOADER.of.

The OF "system call" set (think of it as the OF "OS") is now tokenized:

[Remember that tokenize activates compile-time routines defined in the meta-

compiler that then generates code that goes into the OF image]

tokenize ALLOC-MEM.of -- Pointer-based memory allocator using "buddy" algorithm.
tokenize USER-INTERFACE.of -- Global variables, "main" code path, lots of dispatching. Because most globals that everybody needs are defined here, it is included early in the compilation process not because the code executes "early" but for compilation purposes since no forward symbolic references are allowed.
tokenize ALARM.of -- Background task dispatch (this is the only multitasking that happens).
tokenize EDITOR.of -- User shell input / output behavior.
tokenize TERMINAL.of -- Character generator for user shell using a video card instead of serial terminal.
tokenize DEVICE-TREE.of -- Device tree generation: Adding nodes, adding properties to nodes.
tokenize RESOLVE.of -- Per-instance runtime model for execution context, local variables, Device Tree pathname interpretation for code ("words") in node execution, pathname open / close with constructors / destructors and call inheritance, call-by-name model, and more.

G.4.1.8. Compiling OF Basic Services

At this point -- after OF "OS"-like files compilation -- we have a very basic operating system with a memory and run model; additional system calls are now tokenized, but with token numbers greater than 0x800 (the OF "OS" system calls are assigned low token numbers) (???? are these token numbers not to be confused with FCODE bytecode token numbers):

[Remember that tokenize activates compile-time routines defined in the meta-

compiler that then generates code that goes into the OF image]

tokenize VIRT-MEM.of -- Services that track major large allocations (other than alloc-mem) .
tokenize FIRMWARE-DEBUG.of -- FCODE disassembler (see), step-and-trace debugger.
tokenize HOST-PCI.of -- Services related to FCODE probing on expansion card ROMs and PCI probing even if there is no expansion card ROM; finding and execution of FCODE, node creation, assignment of default or properties in the new node if necessary.
tokenize NVRAM-CHRP.of -- High-level partition-based data storage interface for non-volatile RAM (NVRAM); this is the "file system" only; it makes use of low level NVRAM I/O routines for whatever the platform's NVRAM technology might be.
tokenize LOADER.of -- Executable program loader from a mass storage device; for example, one can load, prepare for execution, execute, and return to OF, programs in at least the following formats: XCOFF, PEF, OF FCODE, OF text, CHRP-BOOT.
tokenize CLIENT-DEBUG.of -- ?????no idea what this is???????.
tokenize DBDMA.of -- Definitions of Apple DMA engine data structures.

G.4.1.9. Compiling OF Machine-Specific Personality

At this point -- after a more complete set of OF "OS" is in place -- META-COMPILER.fth perfoms a TOKENIZE of the project's OFSources:Projects:*:THE-TREE.of. It is here that the personality of the specific machine is defined.

THE-TREE.of contains a call to init-device-tree and then a great number of nested new-device / finish-device call pairs that will be executed during detokenization time soon after kernel initialization after being called from Hardware Init; this defines the structure and contents of the project's Device Tree.

Because a Device Tree, with all its nodes containing properties and code "words", is a large hierarchial structure, and because many peices are shared among projects, it is split into pieces in different source files. The THE-TREE.of file is mostly only a "master" file that text-includes other files as needed for the specific machine, as well as define some basic per-machine items as device-alias and main "model" property definitions.

Starting with a project's THE-TREE.of, new-device / finish-device pairs, which start / end a new node, contain FLOAD source text includes of the following basic services:

[Remember that fload is a compile-time aforth source text include; these floads

cause the addition of code that goes into the OF image, and also going into the OF

image are their surrounding new-device / finish-device commands; thus the result is

a big hierarchial chain of commands including new-device and finish-device to start

and end nodes, plus code that defines words (routines) and properties in these nodes;

in other words, the entire Device Tree]

new-device/fload ROOT.of -- Generates root node of Device Tree (contains official copyright string that OS loaders look for).
new-device/fload CPUs.of -- Generates properties about CPU speed, cache size, etc, ?????and base class implementation of CLAIM????????.
new-device/fload MEMORY.of -- Generates properties about memory size and attributes.
new-device/fload CLIENT-INTERFACE.of-- Provides a callback service whereby programs that OF has loaded and run are able to use OF services (to print results, to query the Device Tree, etc).
new-device/fload ROM-NODE.of -- Generates properties about ROM versioning. This, together with the properties at the root Device Tree level, etc, is used among other things by Apple System Profiler (ASP) which displays configuration information.

G.4.1.10. Compiling OF High Level Common Library Services

At this point -- after the basic machine-specific structure-defining sources have been compiled -- THE-TREE.of creates a "packages" node with collections of routines that implement relatively high-level services that we want to be included for this machine:

[Remember that fload is a compile-time aforth source text include; these floads

cause the addition of code that goes into the OF image, and also going into the OF

image are their surrounding new-device / finish-device commands; thus the result is

a big hierarchial chain of commands including new-device and finish-device to start

and end nodes, plus code that defines words (routines) and properties in these nodes;

in other words, the entire Device Tree]

new-device/fload DEBLOCKER.of -- Random-access byte-wise interface for block drivers.
new-device/fload DISK-LABEL.of -- Read-only multiple hierarchial file systems.
new-device/fload OBP-TFTP.of -- Network Open Boot Protocol / Trivial FTP Protocol.
new-device/fload MAC-PARTS.of -- Mass storage partitioning format interpretation.
new-device/fload MAC-FILES.of -- Standard MacOS file system (used by disk-label.of).
new-device/fload HFS-PLUS-FILES.of-- Extended MacOS file system..
new-device/fload FAT-FILES.of -- Microsoft file system.
new-device/fload ISO-9660-FILES.of-- ISO 9660 file system for CDs.
new-device/fload BOOTINFO-LOADER.of-- CHRP (MacOS, MacOS-X) format loader (used by loader.of) (contains tagged fields with executable machine code, data, versioning, graphics, text).
new-device/fload XCOFF-LOADER.of -- XCOFF format loader (executable machine code).
new-device/fload PE-LOADER.of -- PEF format loader (executable machine code).
new-device/fload ELF-LOADER.of -- ELF format loader (executable machine code).
new-device/fload USB-HID-CLASS.of-- USB Human Interface Device drivers.
new-device/fload ATA-DISK.of -- ATA (HD) format driver (protocol only; hardware-agnostic).
new-device/fload ATAPI-DISK.of -- ATAPI (CD, ZIP, HD, etc) format driver (protocol only; hardware-agnostic).
new-device/fload PSUEDO-USB.of -- USB controller driver probe to allow multiple USB controllers.
new-device/fload PSUEDO-HID.of -- Dispatch stub to allow simultaneous USB and ADB.
new-device/fload RTAS-NODE.of -- Creates node that provides address of RTAS routines for callback use (do not confuse with Client Interface).
new-device/fload BOOTPATH-SEARCH.of-- Boot list generator and probe facilities for Multi-Boot.
new-device/fload MULTI-BOOT.of -- High-level Macintosh OS boot search behaviors.

G.4.1.11. Compiling OF Bus Node Creators

At this point -- with a set of high-level services and machine-specific definitions in place for symbolic back-reference at compile time -- THE-TREE.of includes the source files that create the nodes for the I/O services -- PCI based, including on the main logic board (Yosemite example) a main PCI controller, a PCI-PCI bridge, and a Macintosh legacy I/O ASIC:

[Remember that fload is a compile-time aforth source text include; these floads

cause the addition of code that goes into the OF image, and also going into the OF

image are their surrounding new-device / finish-device commands; thus the result is

a big hierarchial chain of commands including new-device and finish-device to start

and end nodes, plus code that defines words (routines) and properties in these nodes;

in other words, the entire Device Tree]

new-device/fload GRACKLE.of -- Creates main "/pci" node and implements PCI Configuration Space accessors; conditional per-machine code further defines runtime probe activity, the settings of slot-names properties, etc.
new-device/fload GRACKLE-PCI.of -- Creates node for main logic board PCI-PCI bridge, for those machines that have one (do not confuse with PCI-PCI.of, which defines standard nodes for external bridge cards, such as those for expansion chassis).
new-device/fload HEATHROW.of -- Creates node for Macintosh legacy I/O ASIC. At runtime, sets up interrupt handling and special I/O features, many of which are specific to the specific machine but must be set up at runtime because the Heathrow family is used on all Macintosh products. Defines nodes for serial ports, sound, ADB, etc; a list of files it in turn creates nodes for and fills those nodes with floads:

MESH.of -- Narrow-SCSI driver.
BURGANDY.of -- Apple audio ASIC CODEC driver.
SWIM3.of -- Apple GCR / MFM floppy driver.
VIA-CUDA.of -- Apple power management microcontroller "driver" (requestor).
VIA-PMU.of -- Apple power management microcontroller "driver" (requestor).
ADB-KBD.of -- Apple ADB keyboard "driver" (requestor).
PMU-NVRAM.of -- NVRAM driver for machines with PMU family ASICs (portables).
HEATHROW-NVRAM.of -- NVRAM driver for machines with Heathrow family ASICs (desktops / minitowers).
RTC.of -- Driver for PC calendar device (not used recently).
BMAC.of -- Ethernet driver.

Now, META-COMPILER.fth is finished tokenizing (using words in META-TOKENZIZER.fth) the source text in THE-TREE.of and all of THE-TREE's floaded files.

G.4.1.12. Compiling More OF Libraries and Including External Code

At this point -- as the last stage of the compile -- META-COMPILER.fth defines some compile-time-only words for, and then proceeds with, its next and final task: Tokenizing source text from a few more files and linking them in an area not for general access but one that is activated (byte-loaded) either explicitly at runtime by calling byte-load-file, or automatically by a matchup of PCI Configuration register values.

Certain 3rd-party OF drivers which we want to include with the motherboard BootROM are included via this mechanism; an example is an on-board 3rd-party video ASIC for which they provide the OF driver. Another example is certain OS drivers (not always recommended for BootROM inclusion), such as the Lower Ethernet driver.

This is done by the equivalent of floading a project-specific file called OFSources:Projects:*:THE-FILES.of. Even though it is floaded, the THE-FILES.of file contains only tokenize-list compile-time commands, thus turning the source text into a collection of tokens (not detokenized stuff like byte-loader) anyway, each with two tags for runtime loading.

The tags can be the PCI Device-ID-plus-Vendor-ID and PCI Class ID; they can be one or two wildcards; or they can be generic small integers used by the main code when doing byte-load-file. "-1" for a parameter specifies wildcard; a small integer close to zero will almost never conflict with a real PCI ID. An attempt is made at runtime to match a currently-being-probed PCI device with one of these tagged token collections; this is how a driver in the BootROM can automatically be loaded.

Think of it as a sort of file system in which these code sections are stored away at compile time, ready for "loading" at runtime.

A typical (Yosemite example) THE-FILES.of file has the following entries:

-1 2 tokenize-list SCC.of -- Serial port "byte" type driver.
-1 3 tokenize-list SCSI-DISK.of -- MESH narrow SCSI "block" type driver.
-1 6 tokenize-list IDE-NODE.of -- Ultra ATA "AIM" (parent controller) driver.
h# 06461095 -1 tokenize-list IDE-PCI.of -- Ultra ATA parent controller driver, part 2.
-1 4 tokenize-list IDE-DISK.of -- Ultra ATA "block" type driver.
-1 5 tokenize-list IDE-CDROM.of -- Ultra ATA "block" type driver.
-1 7 tokenize-list SCSI-TAPE.of -- MESH narrow SCSI "block" type driver.
-1 10 tokenize-list HEATHROW-IDE.of -- Standard ATA "AIM" (parent controller) driver.
-1 11 tokenize-list ETHERNET-LOWER-ndrv.of -- "Lower" run time driver (MacOS code).
-1 h# 00060400 tokenize-list PCI-PCI.of -- PCI-PCI Bridge node definition.
-1 h# 000C0310 tokenize-list USB-OPENHCI.of -- An OpenHCI USB controller.

G.4.2. OF Kernel Runtime Initialization Sequence

The code in OFSources:Kernel:KERNEL.fas gets control from Hardware Init. An OF runtime environment will be created and execution will from on then be FCODE (bytecode) based (until the OS is booted and gains control).

G.4.2.1 About the Kernel Source Code Text

Although KERNEL.fas contains the executable code, one should also examine META-COMPILER.fth because (in addition to its primary purpose of being the "compiler") it contains constants and data structures such as StartVec.

While browsing the OF Kernel and Metacompiler source files, keep in mind that it is derived from before the NewWorld architecture, and so there are now-misleading references to such things as "returning to Hardware Init (or Nanokernel)" and "running out of RAM now":

Before NewWorld, the OF Kernel was in ROM and uncompressed itself into RAM; now, that uncompression is done entirely by Hardware Init itself before OF is ever run.
And the Nanokernel is something that is a small part of an OS that to OF is just another program, not any kind of "next step" after returning from OF -- in NewWorld ROMs, OF never returns; it only executes programs that may never return to OF.
There may be other such examples.

Since the act of KERNEL.fas being compiled is really the compile-time act of execution by aforth of words, such "execution" is not limited to what is in META-COMPILER.fth and asmPowerPC.fth -- there are places in KERNEL.fas where there is inline FORTH code that does, for example, a loop; think of this as a compile-time macro that loops to emit lots of output code. Or, for another example, the setting of a variable that must be regarded as a compile-time macro variable. Of course, there is a more contentional use of this technique also: this is how compile-time expressions are evaluated. Here are the two examples cited above:

Communicating compile time globally with macros:

tHere constant <ALARM> \ for internal branches

tHere to &<ALARM> \ for ALARM?, macro

Macro loop to generate lots of code:

Tcode (local!) \ single name, vectored entries

8 0 do

%r3 i cells ldk,

<local!> b,

loop

There may be other such examples.

G.4.2.2. Runtime Model Implemented by Kernel

Refer first to G.4.1.1 for a description of the overall interpretation model and how everything is defined as a runtime stream, and that nothing is really "compiled" (routines are created on the fly with colon definitions, as are variables, etc), only compressed into a token stream.

Apple's OF implementation is direct-threaded; that is, instead of a strictly-interpreting emulator which is the only machine code entity that runs (interpreting a fully arbitrary "code" stream), Apple's OF code in memory consists of little pieces of machine code which is actually executed, linked with glue consisting of branches and headers with attribute bits and (optional) symbols. A runtime convention is defined which provides for data stack, execution stack, etc, via present data structures and register conventions.

The advantage of a direct-threaded model is that it is faster, in some ways easier to debug, and easier to patch (see brpatch and brpatch descriptions). The disadvantage is that a fully-interpreted emulator might provide more control (step-and-trace debugging and perhaps other advantages). Nevertheless, a step-and-trace debugger exists (see debug description).

FCODE is first brought into memory by reading the token stream from its source. That source can be a card's expansion ROM found during probe, code in the BootROM that is matched with a card or device, code in the BootROM that is automatically made part of a Device Tree node during its creation, a file read in from disk, etc.

The token stream is converted into a form suitable for execution by byte-loader. Here, it reads bytecodes in using a deferred word accessor routine ("&FC") (so that the source of the incoming byte stream can be redirected) and then generates the proper image stream in memory that corresponds to the FCODE bytecodes. This memory image consists of actual PPC machine code branches instead of loop-commanding bytecodes, for example, machine code to load a constant into a register instead of an abstract bytecode commanding the same, etc.

A word (routine, variable, etc) in memory in ready-to-"execute" form looks like this; this is defined in META-COMPILER.fth (because that is what has to create this format as part of Apple's BootROM image) and also in BYTE-LOADER.of (because that is what has to "use" this format at runtime):

OF Runtime Memory Layout of a Word

Offset	Section Start / Examples	Item / Name	Format	Description
`+ 0` (decimal)	Start of "Header" section. Header address points here. To get the header address, do "`['] foo xt>hdr`" or use this table.	Link `>h.link`	32-bit, 4-byte, (big or little)-endian, virtual address pointer.	Points to the word created just before this one; that word's link in turn points to the one before that, and so on; final (first-created) word's link is `NULL`.
`+ 4` (decimal)	header (continued)	Flags `>h.flags`	8-bit byte, boolean bit field. Bit [`7`] = FINDABLE Bit [`6`] = IMMEDIATE Bit [`5`] = HEADERLESS Bit [`4`] = ALIAS Bit [`3`] = INSTANCE Bit [`3:0`] = Unused	Flags that indicate general state independent from its creation type.
`+ 5` (decimal)	header (continued)	Creation Type `>h.ctype`	8-bit byte value. `0xB7` = routine (`:`). 0x`BA` = `constant` 0x`B8` = `value` 0x`BB` = `create` 0x`B9` = `variable` 0x`BD` = `buffer:` 0x`BC` = `defer` 0x`BE` = `field` 0x`BF` = "primitive" definition (`code`); raw machine code to follow.	Type from a sematic and storage point of view: Is it a colon definition, space-allocating buffer, variable, etc.
`+ 6` (decimal)	header (continued)	Token `>h.token`	16-bit, 2-byte (big or little)-endian, token number.	Token number, same as FCODE numbers for "system calls"; `0x800`-based for "user" code.
`+ 8` (decimal)	header (continued)	Count `>h.count`	8-bit byte.	Length of symbolic name of word (if "headers are on").
`+ 9` (decimal)	header (continued)	Name `>h.name`	8-bit byte characters. Count+Name form a pstring.	Text of symbolic name of word (if "headers are on").
`+ 9` (decimal) `+ >h.count`	padding	Padding	Zeroes to pad for 4-byte-alignment.	Make the next address aligned because PPC machine code follows.
`+ 9` (decimal) `+ >h.count` `+` alignment	Start of "Data" (code) section. Tick ( `[']` ) address = execution token ("xt") Points Here. To get the execution token address, do "`['] foo`". To execute it , do "`['] foo execute`".	Data	PPC machine instructions, which are always 32-bit, 4-byte (big or little)-endian quantities on 4-byte boundaries.	Machine code goes here. This is the semantic or "working" part of the word that actually "does" something and thus is in the thread of machine code execution (even if it is a `constant`, its job is still to load a register). The code here is usually very simple, consisting of constant data and branch-and-link (subroutine) calls, but can be fully freeform as with primitives.

It is instructive to type the following and compare it to the table above:

: foo " Hello world" type cr ;

foo

see foo

['] foo u.

['] foo (see)

['] foo 100 dump

['] foo d# 16 - 100 dumpl

Take a close look at the dumpl printout and notice the following:

Symbol text string for "foo".
0x00000000 alignment filler because PPC code is to follow.
Assigned token number (0x800 if done first thing).
The Flags value of 0x80, indicating that is findable but not special in any other way.
The Creation Type value of 0xB7, indicating that this is a routine of OF code (colon definition).
PPC code start with the first instruction of 0x967EFFFC.
"Hello world" string bytes surrounded by the machine code instructions to jump to subroutine to embody the string storage (0x967EFFFC 0x7E6802A6 0x4BF6C339 = stwu r19,-4(r30); mflr r19; bl $-0x93CC8).
PPC Code to call the "type" and "cr" words, and then exit this word (0x4BF723B1 0x4BF7238D 0x4BF6B940 = bl; bl; b).

See also the source file FIRMWARE-DEBUG.of, which contains, among other things, the code for see.

Like any emulation or execution model, all of this direct-threaded code requires some conventions and resources in the form of a return stack for subroutine calling, a data stack for parameter passing and local variables, and an execution context pointer. These conventions are as follows:

OF Runtime Register Conventions

PPC Register	Symbolic Name	Description
`r16`	`rHERE`	Heap pointer -- This is where inline allocations go (`allot`, `l,` , etc).
`r17`	`r$HERE`	Cache-flushes `HERE` -- Normally points to `HERE`, sometimes TOS.
`r18`	`rLR`	Link Register temp -- For branch-implementation FCODEs, etc.
`r19`	`rTOR`	Top of Return Stack (`rRP`) -- For `CATCH`, `EXIT` return to caller's caller, etc.
`r20`	`rTOS`	Top of Data Stack (`rDP`) -- For quick access.
`r21`	`rNOS`	Next of Data Stack (`rDP`) -- For quick access.
`r22`	`rTOL`	Top of Loop Stack (`rLP`) -- For quick access.
`r23`	`rNOL`	Next of Loop Stack (`rLP`) -- For quick access.
`r24`	`rLP`	Loop Stack Pointer -- Tracking nested loops: locations; `i,j` outputters, etc.
`r25`	`rSV`	Start Vector -- Points to a data structure of Kernel globals.
`r26`	`rFP`	Frame Pointer -- Stack used for local variables Apple extension ?????
`r27`	`rEP`	Exception Frame Pointer -- Used only by `CATCH` implementation.
`r28`	`rTTP`	Token Table Pointer -- Translation between token number and code address.
`r29`	`rMySelf`	Execution Context -- Also available thru OF variables; for quick access.
`r30`	`rRP`	Return Stack Pointer -- The OF return stack (routine calling, `>r`, `r>`, etc).
`r31`	`rDP`	Data Stack Pointer -- The OF data stack (`dup`, `swap`, parameters, etc).

G.4.2.3. Runtime Kernel Initialization

The code in OFSources:Kernel:Kernel.fas gets control at the sequence "ROMstartVec org", having been passed r3 as a pointer to a data structure ("Platform Info") described above.

From this time (Hardware Init handoff) to the end of machine-code based kernel init compiled from the two source files KERNEL.fas and BYTE-LOADER.of (after which OF continues to initialize, but does so from detokenized FCODEs), the code flow proceeds as follows:

?????????this is not done (though it's complete and nothing is missed)

In META-COMPILER.fth, the constant ROMreal, which comes from LOWLEVEL.fth, is used to invoke "org", which in asmPowerPC.fth simply advances its output code pointer, and to define and set a value for "'(cold1)". As META-COMPILER.fth floads/evaluate-executes KERNEL.fas contents, code starts to be ????emiotted at this offset with the rest zeros????if not, how????there.
Turn off CPU VM relocation and interrupts.
A data structure ("preferred allocation vector") is set up -1 \ default REAL-BASE, -1 \ default REAL-SIZE, 0xFF800000 default VIRT-BASE, 0x00800000 default LOAD-BASE(for byte-loader's cold-load purposes for getting OF up below?)
restart possibility if endian-ness called for in NVRAM setting is not the same as current
talk about startvec, zero out startvec data structure, begin to fill it in with data from hw init. This happens at KERNEL.fas:"zeroing the whole thing out".
*** in BootROM world, we are alwa" program BAT registers
\ copy the directory info for use later (e.g., RTAS installation) ????? \ When quick restart flag is TR... what is this???
suck up clock speed info from hwinit. This happens at KERNEL.fas:"copy relevant info".
xxxxx. This happens at KERNEL.fas:"Get restart flag".
Zero out Block Address Translation (BAT) VM mapping override registers. This happens at KERNEL.fas:"make sure of unused ones".
VM mapping for /????. This happens at KERNEL.fas:"mapPages".
VM mapping for ???? . This happens at KERNEL.fas:"Map the area".
a bunch of conditionally-compiled PCI / Paddington setups if Logger debugging is enabled, probably so that serial output can be done very soon. This happens at KERNEL.fas:"config-macio".
we copy ourselves . ???this is a leftover from the days when the first part of the OF Kernel was stored in ROM (now everything in KERNEL.fas is already in RAM, decompressed by Hardware Init). This happens at KERNEL.fas:"copy my image above".
Space is allocated and the dedicated runtime registers shown in the table above are initialized for all of the stacks, such as the data stack (pointed to by rDP), return stack (rRP), loop stack (rLP), etc. This happens at KERNEL.fas:"allocate space for stacks".
Code addresses of important items are determined with a runtime offset computation based on hardcoded symbols and are stored in the StartVec data structure. One of the most important is StartVec's >'cold-load, pointing to code in BYTE-LOADER.of; the symbol's code offset is generated at compile time in META-COMPILER.fth:"T' COLD-LOAD offset ROMstartVec >'cold-load TC!". This happens at KERNEL.fas:"convert offsets into RAM startVec".
Endian-reversing might happen

could happen depending on NVRAM setting ???? how does this work???describe control mechanism
Running in both endian modes actually works in OF; booting MacOS does not, however; a crash occurs during the Trampoline code; so we are normally always in big-endian mode.
All OF word images in memory are reversed; this happens at KERNEL.fas:"transforms us into a Little-Endian image".
the processor is set up ????describe????? at KERNEL.fas:"load up regs in BE mode".

The token table is initialized with addresses of known routines (primitives); unused slots are filled with ferror, which causes a controlled crash if an illegal fcode is ever encountered. ????talk about how token table is used?????. This happens at KERNEL.fas:"initialize TokenTable".
A known-invalid value is set for my-self, the execution context pointer, and then the address of the StartVec data structure's >'cold-load value = is acquired, and we drop into common code at "<INIT-WORLD>" that does OF exception handling. After setting up ????my-self ???and????, cold-load is executed. This happens at KERNEL.fas:"startup in COLD".
BYTE-LOADER.of:"COLD-LOAD" does a byte-load of StartVec's >fcImage byte stream. The act of this byte-loading as caused by byte codes compiled from source code in USER-INTERFACE.of causes (since "loading" is really "evaluating" which means "immediate" code is executed such that routines can be defined and variables set) does a setup of StartVec's >'cold-init to point to USER-INTERFACE.of:"_COLD-INIT".
USER-INTERFACE.of:"_COLD-INIT" runs, and from this point on, initialization continues as OF code, described in the next section. Incidentally, this code flow is similar to a default CATCH occurrence (usually an OF program crash due to a bad memory reference); the interrupt handler finishes up by joining this same code.

4.2.4. Runtime Kernel Noninitialization Resident Services

In summary, the virtual machine is implemented by virtue of the established runtime conventions and the following actions of the OF Kernel:

Set up the environment as described above, and begin execution with a hard-coded choice of word.
Define OF "primitive" routine implementations that cannot be further reduced by OF code, such as memory reads and writes, loops and branching, etc.

In fact, a quick look towards the bottom half or so of the KERNEL.fas source file will show lots of small "TCODE" sections, each of which implements an FCODE. These are all "primitives", but note that there are both primitives such as "w!" or "map-page" which are directly used by programmers as well as ones such as "B<LOOP>" which FCODE compilers generate out of "high-level" FORTH-language construct such as loops and case statements.
Note that each primitive ends in a branch of some kind. Direct-threading means that this branch will return to the calling implementation (sometimes called the "data section") of some word, which then may cause a jump to another word.
Throughout all of this, the register conventions described above are maintained. Together with the (data stack, etc) memory that these registers point to, these elements for the virtual machine.

Some of the tasks handled by the OF Kernel in addition to implementing the execution model:

Define as OF "primitives" often-used, short, low-level routines for speed optimization.
Provide machine-code Client Interface (CI) entry / exit glue between the caller and the OF world.

In addition to creating an environment for and implementing the runtime of the direct-threaded OF code execution world, the OF Kernel supports the "Client Interface", allowing on-demand execution of OF services by machine code that executes outside of OF (ie, callbacks from a client program that OF has previously XCOFF-loaded). The routines CIExit and CIEntry implement this outside gateway. ???describe more

use of timing input
DSI (Data Storage Interrupt) exception handling; this is a PPC requirement because even though OF does not do any disk-based virtual memory (VM) demand paging, it does to VM remapping.
xxxx exception handling for alarm tasks
xxxx exception handing for CATCH occurences (bad memory addresses for reads/writes)
sss

G.4.3. OF (Post-Kernel) Code Initialization Sequence

As described above, OF code starts at USER-INTERFACE.of:"_COLD-INIT" from the initial byte-loader handoff. At this point OF is still not fully initialized, and beyond that the probe (Device Tree generation) and "user" code must be done, but from this point on, we are fully in the OF world in the sense that there is now a simple correlation between OF source files and code that runs; moreover, logger / time-stamp calls now work, so the engineer can readily see what is happening.

G.4.3.1. OF Probe

G.4.3.2. OF User-Interface setup

G.4.3.3. OF User Interface (Shell)

If Command-Option-O-F, is pressed, or if the NVRAM setting "auto-boot?" is false, then the Open Firmware User Interface command line screen is entered for debugging. See the References section for documentation. Depending on the NVRAM settings for "input-device" and "output-device" (keyboard/screen vs. scca/scca, for example), the command line interface occurs on one of the video screens or the serial port.

G.4.3.3.1. OF User Interface Console Device Manual Control

As a practical matter, normally the User Interface output is displayed on one of the video node devices and input is accepted from the sum of all currently connected ADB and USB keyboard ("dueling keyboards" ("dueling mice", also)). Typing "scca io" will transfer the console to the serial port, or setting the NVRAM settings "input-device" and "output-device" to "scca" will cause the console to come up on the serial port.

G.4.3.3.2. Default Console Device selection

Events proceed in roughly the following order; we have presented output only; similar things happen for input; the following are all involved: "screen" alias, _DISPLAY global, _SCREEN-IHANDLE global, STDOUT global, OUTPUT routine, INSTALL-CONSOLE routine, INSTALL-SCREEN routine, "use-serial?" NVRAM setting, "output-device" NVRAM setting, and more:

USER-INTERFACE.of:COLD-INIT runs PROBE-ALL
_DISPLAY global set by HOST-PCI.of probe process using RESOLVE.of:?has-display routine
RESOLVE.of:INSTALL-CONSOLE is run by USER-INTERFACE.of:COLD-INIT
At this point in RESOLVE.of:INSTALL-CONSOLE, if the _DISPLAY global is set and the "screen" devalias is blank, as will usually be the case (it is not in most devalias lists in THE-TREE.of's), the "screen" devalias is created to be a path string that is the _DISPLAY phandle
Note again that "scca" and "screen" are devalias lhs whose rhs's are output device paths; note also that "output-device" is an NVRAM lhs whose rhs is an output device path, usually in the form using the "scca" or "screen" devalias
The RESOLVE.of:INSTALL-CONSOLE routine calls the RESOLVE.of:OUTPUT routine with the rhs setting of NVRAM " output-device" lhs
The RESOLVE.of:OUTPUT routine tries to OPEN-DEV the new output device; if succeed, put the ihandle into the "stdout" variable and close the old one; if fail, nothing changes

Note that INSTALL-SCREEN, which tries to open-dev the "screen" alias explicitly and sets the global _SCREEN-IHANDLE, is not used by the OF user interface by default but is used by Mac-Boot, because Mac-Boot implements a graphical interface (and indeed, for debugging, the serial port node "scca" can be used as the OF user interface console while it does graphics on a graphics node "screen").

The screen device that is opened will be the last one whose phandle was stored in the _DISPLAY global; see HOST-PCI.of and RESOLVE.of's SearchForDisplay and ?has-display routines.

????is the above all correct????

G.4.4. OF User Program Execution

user interface or not, then NVRAM boot-command or mac-boot

usually from here on we do mac-boot / multi-boot, which searched for an OS to boot

then we boot the OS using the <CHRP-BOOT> loader; it runs, and we are off booting the OS; for a full description, see the big master boot play-by-play table elsewhere in here, General NewWorld BootROM-to-MacOS Boot Overview.

G.5. Mass Storage

G.5.1. file I/O standard features

All device drivers make use of the disk-label package which provides multiple partitioning and file system interpretation services, including directory printout, file reading across directories (but not writing) by name or MacOS type.

G.5.3. Mass storage pathname syntax

OF (starting with OF-3) supports the mass storage pathname syntax as described in the IEEE and Firmworks documentation:

Mass Storage Syntax

File Pathname= [driver-spec][device-spec][volume-spec][file-spec]

driver-spec is the path to a device driver, that is a node of device_type "block"

driver-spec = [devalias[/further/qualified] | [/full/path/starting/with/slash]

device-spec is the ID of the targeted drive on the bus, ie, a SCSI ID, or 0/1 for Master/Slave

device-spec = [@id-in-hex]

volume-spec is the location of the desired data partition within the drive

volume-spec = [,lun-in-hex][:[partition-in-decimal]]

· Partition numbers are on-disk partition numbers, usually the first MacOS partition is on 4 or 5.

· Specifying a 0 for the partition number causes no partitioning interpretation to take place; use this to access raw data from the beginning of the disk or lun.

· Not specifying a partition number (but the comma must be included) causes a search for the first acceptable partition to take place.

file-spec is the location of the file on the file system volume

file-spec = [,path-start[path-to-file] | [:type]]

· path-start = \ | \\A single backslash means from root of file system, a double backslash means from the System Folder directory

· path-to-file = pathname-components\with\backslashes\for\directories

· pathname-components can have "%xx" for special character escape, where "xx" is a two-character hex ASCII value. UniCode values may also be specified as "%xxxx".

· type is a 4-character MacOS filetype to search for.

Notes:

The device id is given in hex, the lun is given in hex, but the partition is given in decimal.
See below for search policies for finding partitions and file systems.

Examples:

hd:,\\:tbxi accesses the device driver and id pointed to by the "hd" alias, the first found partition that is likely to have a file system on it, the "System Folder" directory, and the first found file of type 'tbxi' (usually Mac OS ROM).

hd:5,\\:tbxi accesses the device driver and id pointed to by the "hd" alias, whatever file sytem is on partition 5, the "System Folder" directory, and the first found file of type 'tbxi' (usually Mac OS ROM).

mac-io/ata-3/disk@0:5,\\Mac%20OS%20ROM accomplishes the same thing; note the use of escapes to specify the spaces in "Mac OS ROM"; note that an alias can be further qualified; note that the id and partition number are explicitly specified.

mac-io/ata-3/disk@0:5,\System%20Folder\Mac%20OS%20ROM accomplishes the same thing; note that this time we are specifying the directory explicitly instead of using the "\\" shorthand for the System Folder directory.

/pci@80000000/pci-bridge@d/pci-ata@1/ata-4@0/disk@0,0:0 accesses the "whole device" without partitioning interpretation, because the partition number given is zero. The ihandle returned from the open-dev call can be used to read bytes directly from the very beginning of the disk.

/pci@80000000/pci-bridge@d/pci-ata@1/ata-4@0/disk@0,0:5 accesses the raw data within partition 5 (or any nonzero partition number of 1 or greater), because no file specification was given. The ihandle returned from the open-dev call can be used to read bytes directly from the beginning of that particular volume of the disk, which may be a driver partition, empty partition, or the raw bytes of a filesystem.

mac-io/ata-3/disk@1:4,\abc\file accesses the file on ata-3 bus, device 1, partition 4, directory "abc", filename "file" (for Yosemite this would be on the ZIP disk).

G.5.4. Mass storage semantics

G.5.4.1. The way drivers and removable drivers are supposed to behave

put here the stuff at beginning of bps docs about first open-dev vs. all others thereafter wrt auto-inject and wait-for-spinup; and that they're required to 1) do auto inject and/or spinup 1st time but not any other times; 2) not do it 2nd time and return error immediately

G.5.4.2. Partition search policies

If the pathname syntax specifies "no partitioning interpretation", then the byte offset from the beginning of the disk is zero. Otherwise, one of the following policies as defined in {BR}:OF:OFSources:Common:MAC-PARTS.of applies.

If the pathname syntax specifies a particular partition to access, then the following algorithm is used to compute the byte offset from the beginning of the disk:

The partition is accessed by using the OF partition number given, multiplying by 0x200, and interpreting the data as a Macintosh partition map entry as defined in Inside Macintosh: Devices: 3-25.
The partition must be "valid". "Valid" means: The partition map entry block's signature "pmSig" field (+0 decimal offset) must be "PM" (0x504d 16-bit big-endian) and the partition type "pmPartType" field (+48 decimal offset) must start with the case-sensitive characters "Apple_HFS" or "Apple_Boot" (that is, Apple_HFS*|Apple_Boot* is matched).

If the pathname syntax specifies to "search for the first partition" (the "first" reasonable partition; that is, the first one likely to contain a file system, not a driver or empty or whatever), then the following algorithm is used to compute the byte offset from the beginning of the disk:

A search is done by walking the various partition map entries from the beginning of the disk; the first "valid" partition, as specified above, wins.
This search is started by reading 0x200 bytes starting at 0x200 from the beginning of the disk (that is, one "block" starting at "block" 1 (regardless of the actual device driver block size, partition format "blocks" are apparently always 0x200 bytes long)). This block's "pmMapBlkCnt" field (+4 decimal offset) is interpreted at a 32-bit big-endian number indicating the number of partitions to search.
The loop proceeds for that many iterations, at each iteration reading another 0x200-byte partition map entry block and examining it for being "valid"; the first "valid" one found stops the loop at that partition map entry block. The 1,2,3... loop index, counting from "1" being the block at 0x200 byte offset from the start of disk, is the OF partition number.

Regardless of how the partition number is arrived at between the two methods above:

The field "pmPyPartStart" (+8 decimal offset) is interpreted as 32-bit big-endian number indicating the start of the partition data (ie, the file system) from the beginning of the disk.
The field "pmPartBlkCnt" (+12 decimal offset) is interpreted as 32-bit big-endian number indicating the size of the partition data (ie, the file system) in units of 0x200-bytes.

G.5.4.3. File system search policies

If the pathname syntax specifies a named file on a volume, OF examines the given volume, tries to identify its file system, and if it recognizes the file system, interprets the data on the volume as such and attempts to access the requested directory and file.

OF contains several file system interpreters; in general, these are implemented as read-only, since the primary function of OF is to load an OS and file system write operations are much more difficult to implement and require more ROM space.

The file systems supported are as follows:

OF File System Support (Read-Only)

Name	Source File	Identification Basis	Comments
HFS	`MAC-FILES.of`	"`BD`" (`0x4244`) 16-bit big-endian at beginning (+`0` offset)	Mac OS Standard
HFS Plus	`HFS-PLUS-FILES.of`	"`H+`" (`0x482b`) 16-bit big-endian at beginning (+`0` offset), or the same as standard HFS above but with `0x482b` 16-bit big-endian at `drEmbedSigWord` (`+0x7c` offset )	Mac OS Extended
`BOOTP, TFTP`	`OBP-TFTP.of`	This does not really belong in this table but is included here because it is an acquisition method for files, even though the intelligence is at the server	Network booting using the `BOOTP` request and Trivial File Transfer Protocol (TFTP) in which a server responds to a simple broadcast request on the local subnet
`FAT, IBM, Microsoft`	`FAT-FILES.of`	Not on a partition (bug?), and `0xAA55` 16-bit little-endian in boot block (+`0x1fe` offset)	Windows and DOS OS
`ISO 9660`	`ISO-9660-FILES.of`	Not on a partition (not a big, apparently never on a partition), and 8-bit bytes: `0x01`, '`C`', '`D`', '`0`', '`0`', '`1`' at "starting block" (+`0x8000` offset)	File system for CD-ROM media

G.5.4.4. Load formats

beyond the file systems, there are the various load formats

x.x special Apple OF features not in IEEE standard or Firmworks extensions

G.6. Booting

Boot Search refers to the process of finding an OS to boot from. Pre-NewWorld, this used to be done by the MacOS ROM. Now, it is done by the BootROM.

This process is less trivial than it might appear at first due to the user interface requirements (main video screen clues, "snag boot" keypresses, etc) and the variety of devices that are encountered across machines (101, Yosemite, etc), configurations (what kind of hardware, built-to-order, etc), and sessions (any external device a user has plugged in, removable media, etc). Different machines having different search order preferences, OF/OS pathname syntax translation, speed performance, and other things, become issues.

Previously, Macintosh machines with large MacOS ROMs contained full-featured device drivers, OS services, and high-level boot search algorithms. With the MacOS in ROM gone, the task of loading and booting MacOS or any other OS falls on the BootROM. Therefore, in addition to handling the boot search itself, the BootROM must have at least minimally working device drivers, partitioning and file system interpreters, and code prepare-for-execution loaders.

G.6.1. Traditional Apple Boot Search behavior

What follows is a loose definition of what was traditionally called "StartSearch".

The way in which the boot search process occurs is a result of the evolution of Apple products. The Apple II relied on the user to type a command to run drive firmware; then a ROM upgrade preformed a slot search and attempted a boot from the first disk drive it could find. The Macintosh first had a single floppy drive, which was then expanded to an external hard drive that functioned much like a floppy, then internal hard drives appeared, etc, all of which had to be scanned in turn for boot blocks. As machines with slots and then multiple types of removable devices beside just floppies (CDs) appeared and various override keypresses were provided, the situation got increasingly complex.

Just before the BootROM was introduced, MacOS ROMs performed the following steps (simplified?):

Phase 1, in which the mouse button would eject the floppy disk (all machines had floppy drives), and if the "C" key was held down, an attempt was made to boot the CD.
Phase 2, in which the device selected in the Startup Disk Control Panel would be alternately tried with the floppy drive, until one of them became ready for booting or had bootable media, for about 8 seconds.
Phase 3, in which all devices known would be tried for booting, round-robin style.
Network booting was not supported?????
Was plug-in card booting supported????? Even if it was supported, it was only supported for devises that look like a SCSI or ATA card??????
RAID booting was supported (unlike current OF) because most software RAID implementations work by writing a specialized OS disk driver into the driver partition of the RAID-striped devices; thus when the OS loads the driver, the RAID scheme was known and implemented
All booting occurred by means of the search for a boot block of 68x code bytes that were read in (not load-prepared) and jumped to; no file system knowledge (but yes partitioning knowledge)

G.6.2. Definition of current Boot Search behavior

The end effect of the StartSearch behavior described above had to be replicated in a the "NewWorld" BootROM environment. Without an OS in ROM available, the process of searching for a bootable disk as above while presenting a search algorithm with key overrides and graphical feedback nevertheless had to be implemented

In addition, the decision was made to not rely on a boot block-style boot loader, but rather have it be a file on a filesystem on a disk. This is because the old bootblock format requires the existence of an emulator for the 68x code, MacOS-X probably did not want to hack bootblock contents that "looked" like the old bootblock format, and perhaps most importantly, because the MacOS "ROM"-in-RAM (and the MacOS-X kernel or kernel loader, for that matter) may have been too large (3MBytes) for a reasonable bootblock implementation.

The steps below are followed in order.

StartSearch Process (in time order)

Before beginning the search process, an inventory is made regarding which devices are available as potential boot targets. This will vary depending on the machine, removable media devices, and removable devices, or even power-up status of connected devices. In pre-BootROM machines, lots of already-running MacOS driver and bus manager software provides MacOS StartSearch with this information; in BootROM machines, this information is gathered by BootPath-Search and provided to MultiBoot/Mac-Boot.

In BootROM machines, a list of boot possibilities is created. This list then forms the basis for, among other things, the amount and order of devices to try in Phase 3 (below). The list is a list of OF paths and is generated as follows:

An "ls" style depth-first Device Tree traversal to collect driver nodes of type "block", "byte", or "network".
Elimination of those items specified by the machine-specific "no-boot" property in "aliases".
Putting at beginning those items specified by the machine-specific "first-boot" property in "aliases".
Putting next those items specified by the machine-specific "second-boot" property in "aliases".
Putting last those items specified by the machine-specific "last-boot" property in "aliases".
Note that items not specified as first/second/last end up between second and last and then in Device Tree order.
If the device is narrow SCSI, create 8 entries for it in the list, one for each id.
If the device is wide SCSI, create 16 entries for it in the list, one for each id.
If the device is ATA, create 2 entries for it in the list, one for each (master/slave) "id".
If the device is floppy, network, or some other device without IDs, then there is just 1 entry for it so far.
If the device is partitionable, create 25 entries for each entry.
If the device supports logical unit numbers (LUN), again multiply entries, but this is not implemented.

At the end of this process, there is a long list of a hundred entries (paths) or so that are boot possibilities. All motherboard and slot devices have been considered. Again, this is only how BootROM machines work.

Name	Video Screen Output	Description
Eject Phase	Gray screen	Some removable-eject devices, such as floppies or ZIP disks but not CDs, have any media in them ejected if the Mouse Button (ADB or USB) is down.
Phase 1 ("Override")	Gray screen	Certain devices will be attempted at this time depending on certain keys (ADB or USB) being held down. This is called "snag booting". If this does not work, then go on to the next phase. As described elsewhere in this document in the section about all the keys that can be held down on boot: "C" key: main CD (1 attempt at finding bootable partition) "D" key: main HD (1 attempt at finding bootable partition) "N" key: network CMD-SFT-OPT-DEL ("CSOD"): skip to Phase 3
Phase 2 ("Selection")	Gray screen	Attempt the boot device setting set by the (MacOS) Startup Disk Control Panel. This is the normal way to boot. On pre-BootROM machines, the control panel setting was encoded in some MacOS PRAM bytes for the traditional StartSearch code to pick up. On BootROM machines, the control panel creates a OF pathname syntax string and writes it to the NVRAM `boot-device` variable for `mac-boot` to pick up. Resetting NVRAM causes `boot-device` to be set to "`hd:,\\:tbxi`" (on Yosemite). This syntax requests a search for the first bootable partition on the "main" hard drive (see devaliases). Since the Control Panel did not set it, no selection appears the first time the user opens it; yet booting is fast until it is set (no going to Phase 3 all the time until a setting is made). Therefore, this is the factory setting. On traditional non-BootROM implementations, this phase used to alternate between trying a non-CD removable device (floppy) and the selected device. This was carried over in the iMac and Yosemite, even though they have no such device (except at development time). Obviously this is a waste of time (8 sec) on BootROM machines, so this alternating behavior has been removed for post-Yosemite machines.
Phase 3 ("Search")	Gray screen with a centered icon: A floppy disk with a flashing "?" (non-BootROM machines) or a blinking MacOS "?" folder sequence (BootROM machines); in both cases, the blinking "?" will always stop at a "happy" state if boot search is successful	When all else has failed, the search phase enters, in which a blinking icon is shown to the user, and all devices which could possibly have something to boot are tried. The description that follows applies to BootROM machines only, although it is very close to pre-BootROM machines: This process continues until success. Since, due to censoring (see below), the list of possibilities collapses rapidly to just a few things to try, this process turns into a loop, repeatedly visiting the same possibilities. On portables the machine will be shut down after a time limit of several minutes in this process, desktops continue indefinetely. The search order is that of device appearance in the Device Tree, as possibly modified by a couple of properties in the specific machine's `aliases` node. Non-removable drives are tried only once (all of the partition possibilities on that drive is said to be "censored"); removable devices of course are tried continuously so that, for example, CD media can be inserted at any time. However, when newly-inserted removable media is tried, its partition map is read, and only partitions that exist on that media are subsequently tried (all of the nonexistant partition possibilities on that media is said to be "censored"); when that media is removed, of course, this behavior is reset for next time, so that, for example, a different CD media can be inserted. A lag of at least one non-inserted cycle If and while CMD-SFT-OPT-DEL ("CSOD") is down, when during the normal course of the search the Control Panel selection is encountered, it is not tried. This is called "override snag booting". Override snag stays in effect for as long as the keys are held down; releasing them opens up the search to include the Control Panel device again, if any There has been some debate about what the effect of CSOD should be with respect to volumes vs. partitions: Right now, it eliminates the whole volume from contention; perhaps this should be only the specific partition on that volume if appropriate. The latter may make more sense on portable machines.

A particular volume can fail a search attempt for at least any of the following reasons (in addition to errors such as out-of-memory, I/O errors, or certain bugs):

The device does not exist.
A (bootable) partition on that device does not exist.
A file system on that partition that the BootROM supports does not exist.
A System Folder on that file system does not exist, or a 'tbxi' file does not exist in the System Folder, or a network server could supply a 'tbxi' file when issued a BOOTP request.
The 'tbxi' file is not a CHRP-format boot ("bootinfo") file.
The 'tbxi' bootinfo file is too downrev for the BootROM to want to run it.
The 'tbxi' bootinfo file runs, but it determines that the BootROM which ran it is too downrev, and thus exits, returning control back to the BootROM.

When boot search is successful, the video screen will change sync and a slighly different gray pattern or color may appear. It is during this time that the "trampoline" code is executing, and super-low level MacOS services such as the nanokernel are started. When the MacOS OS-level managers begin initializing, the "Happy Mac" icon appears. Further booting involves loading of MacOS device drivers, high-level toolbox manager initialization, loading of extensions, and running the Finder and other applications.

The BootROM implements all of these boot search behaviors to the extent they make sense. In addition, future BootROMs may have an "OS Picker" that displays a Graphical User Interface (GUI) menu of boot choices.

G.6.3. Implementation of current Boot Search behavior

G.6.3.1. Overview

For iMac, which was the first NewWorld ROM-in-RAM machine, these services had already been completed (mostly by Ron Hochsprung). However, since the iMac and Yosemite PowerMac G3 schedules overlapped to a great extent, we list the requirements again here:

Working device drivers from all devices for all bootable devices (read only, single-thread only); the iMac had the following drivers that began to work fully really only with its debut in OF-3:

ATA-3 (for HD and CD-ROM but no ZIP, etc)
Ethernet

Working partition handling
Working file system handling (read only)
Working loaders (preparation for execution; ie, CHRP-boot format or XCOFF)
A means of doing a boot search algorithm (MultiBoot and BootPath-Search)
OS support (control panel, shortcircuiting of now-superfluous traditional MacOS "StartSearch" boot search code)

All of the above were sucessfully implemented by summer 1998 for iMac. Additionally, Yosemite imposed the following additional requirements:

ATA-3 ZIP drive support in its ATAPI driver
ATA-4 (Ultra ATA) support
Extension to CHRP-boot format loader to enforce OS version vs. machine version compatibility
Additional evolution (bug fixes, better implementations, required features) in the area of Boot Search / StartSearch support: OS control panel, OS traditional StartSearch shortcircuit, Multiboot, BootPath-Search. These requirements happened because of lack of iMac implementation time and the more open-ended I/O nature of Yosemite (for example, plug-in mass storage PCI cards). See the BootPath-Search document for more information.

Even so, the following boot areas were not addressed:

RAID. This was punted due various issues, including 3rd party involvement that would be needed. We need some general, vendor-independent method of knowing how the data is spread across drives, for example.
ATA-4 non-HD devices (ie, ATAPI devices, such as a CD or ZIP, on the ATA-4 bus). The driver exists, but the open-dev caller has to know beforehand what (ATA/ATAPI) is on the bus; furthermore, it is untested.
FireWire and USB buses can both contain mass storage devices; for the Yosemite timeframe nothing was done, but as of this writing (20-May-1999) Ron Hochsprung is nearing completion on such driver support for future machines.

G.6.3.2. Mac-Boot

The code which implements the high-level decision-making and user-interface policies for the behaviors described above is in {BR}:OF:OFSources:Common:MULTI-BOOT.of. Normally, the "boot-command" NVRAM variable causes executtion of the routine "mac-boot", which is defined therein.

G.6.3.3. Multiboot

The code which implements the high-level decision-making and user-interface policies for the graphical OS Picker menu, which is not described above because as of this writing (21-May-1999) it is not finished is also in the same source file as mac-boot; that is, in {BR}:OF:OFSources:Common:MULTI-BOOT.of.

G.6.3.4. BootPath-Search

Mac-Boot and Multiboot use BootPath-Search as their client; this code is in {BR}:OF:OFSources:Common:BOOTPATH-SEARCH.of. See the document BootPath-Search for a full description.

G.6.3.5. Version enforcement between BootROM and OS

It would be not be appropriate for a BootROM to load an OS that the BootROM and machine features can not support. Usually, such an OS will older than the BootROM and machine. Example: A user tries to boot a 7-year-old OS on a recent machine. That OS does not know enough about the new machine, so the BootROM should not even try to load it.

Likewise, it would not be appropriate for an OS to boot unless that OS can support the machine. After the "cut" described in the paragraph above, this will usually involve an OS that is newer than the BootROM and machine. The danger is that this newer OS may not be new enough. Example: A user tries to boot MacOS 8.5 on a machine that was released together with MacOS 8.0. Support for that machine in the OS does not appear until MacOS 8.6. The 'tbxi' file on MacOS 8.5 (but not 8.6) should thus exit back to the BootROM with an error.

As the above two paragraphs indicate, a two-way version checking is required for full release flexibility and to avoid unsupported or untested BootROM / OS combinations. The checking proceeds as follows:

In the BootROM, The CHRP BootInfo Loader that processes the 'tbxi' file contents checks the list of entries in its "<COMPATIBLE>" tagged section.

These are compared with the BootROM's list of entries in the "/" node's "compatible" property. The code that executes this compare is in {BR}:OF:OFSources:BOOTINFO-LOADER.of; the BootROM's list is in {BR}:OF:OFSources:Projects:{*}:THE-TREE.of, and the 'tbxi' file's list is in {BP}:FCODESrcs:BOOTINFO-LZ.proto.fth.

Between the two lists, at least one case-insensitive match must be made. If not, or if some other error occurs, the caller (mac-boot) will receive that error and no load will have been performed nor memory allocated, and the boot search continues.

In the 'tbxi' file, a series of case-insensitive compares are done between the BootROM that is loading it and a built-in list.

This code is in {BP}:FCODESrcs:BOOTINFO-LZ.proto.fth in the code section for the "<BOOT-SCRIPT>" tagged section.

These two events happen in that order, with an error from either one being grounds for rejection of the boot and for Mac-Boot or Multiboot to try to select another boot file.

This is how system software prevents itself from running on machines that are too old, or for which it was not designed. For example, iMac shipped before Yosemite. Both are OF-3, NewWorld machines. So what prevents a Yosemite CD from erroneously booting an iMac? The second mechanism described above. Later MacOS CDs, on the other hand, might be designed to boot both iMac and Yosemite (and others).

G.6.4. Global Boot Sequence from Reset to MacOS

The events below occur in chronological order during a normal successful boot. This is only a very high-level overview with sometimes arbitrary divisions and is meant for orientation purposes.

Many of the phases below are documented elsewhere, often in this document, in more detail; for specifics on how to enable the various Debugging opportunities, see Global Debug Text Output Facilities; these debug output or stopped interactive debugging opportunities become increasingly sophisticated over time.

????????? THE TABLE BELOW SHOULD BE CHECKED BY SOMEONE FROM MACOS TO MAKE SURE IT'S CORRECT???????????????

General NewWorld BootROM-to-MacOS Boot Overview

Phase	Duration	Events	Executes from	Source code	Debug
Reset	< 1 sec	Power up, reset button, ADB Control Shift Power keys	Hardware	MLB Schematic	Oscilloscope
Boot Block	~ 1 sec (~ 1 minute if big RAM tests)	Black Screen, reset vector, detect warm/cold boots, mininub, call (time-consuming RAM) diagnostics if in factory	BootROM, HW Init's Boot Block reset vector	`{BR}:POST:BootBlock.s`	MiniNub, Logic Analyzer
Hardware Init	2 - 4 sec (mostly boot beep)	Rudamentary ASIC (ie, memory controller) setup, call compulsory diagnostics, such as RAM sizing and ROM checksum, more ASIC setup, Boot Beep, uncompress OF into RAM and jump to it	BootROM	`{BR}:POST:{*}.s`	MiniNub, Logic Analyzer
OF (Init)	< 0.1 sec	Initialize OF kernel; virtual address setup for OF purposes	RAM (copied from compressed image in BootROM)	`{BR}:OF:OFSources:Kernel:META-COMPILER.fth, Kernel.fas, BYTE-LOADER.of`	OF Logger, Logic Analyzer
OF (Probe)	< 2 sec	Build Device Tree; give cards a chance to execute code; final ASIC setup	RAM (copied from compressed image in BootROM)	`{BR}:OF:OFSources:Kernel:USER-INTERFACE.of,Bus,Common:{*}`	OF Logger, deferred text to OF User Interface
OF (User)	< 0.1 sec	Start OF application environment, start OF video driver, White Screen, run OF application	RAM (copied from compressed image in BootROM)	`{BR}:OF:OFSources:Kernel:USER-INTERFACE.of`	OF User Interface
OF (Mac-Boot)	5 - 35 sec (depends on available devices)	Square Corner Gray Screen, look for an OS to boot; if it takes a long time, Blinking MacOS Folder	RAM (copied from compressed image in BootROM)	`{BR}:OF:OFSources:Common:MULTI-BOOT.of`	OF User Interface
Boot Info / CHRP Boot	~ 1 sec	Provide OF boot attempt with header showing compatibility info and icon graphics, do callbacks to OF to get Device Tree Info and do debug output	RAM from `'tbxi'` file ("Mac OS ROM"), from OF text header part	`{BP}:FCODESrcs:BOOTINFO-LZ.proto.fth`	OF Client Interface
Trampoline Code	< 0.5 sec	Uncompress MacOS code, interpret Device Tree contents into data structure for MacOS use later as its traditional UniversalTables structures; use assigned-addresses; add AAPL,xxx properties; build Name Registry	RAM from `'tbxi'` file ("Mac OS ROM"), from executable XCOFF part	`{BP}:FCODESrcs:toMacOS.s, MacOS.c`	OF Client Interface
Nanokernel, 68x Emulator	< 0.5 sec	Set up the low-level runtime MacOS environment: interrupt receiving and dispatch, virtual memory, lowest level OS services for memory, time, and multiple CPU management	RAM from `'tbxi'` file ("Mac OS ROM"), from compressed data part	??????????????	Nanokernel debug screen
68x reset vector; low-level MacOS managers	< 0.5 sec	Memory Manager, Process Manager, Resource Manager, QuickDraw, Mass storage bus Managers (ATA, SCSI, etc)	RAM from `'tbxi'` file ("Mac OS ROM"), from compressed data part	`{SM}:OS:StartMgr:StartInit.a,{*}`	Ad-hoc
MasOS Drivers	~ 0.25 sec	Initialize MacOS video driver, causing Round Corner Gray Screen, mass storage device drivers	RAM from `'tbxi'` file ("Mac OS ROM"), from compressed data part	`{SM}:OS:StartMgr:StartInit.a,{*}`	Ad-hoc
Traditional StartSearch	~ 0.25 sec	Mouse Moves; Old code to look for a bootable (remainder of) MacOS; now slaved to OF choice. In some bug situations one can see the flashing floppy icon here.	RAM from `'tbxi'` file ("Mac OS ROM"), from compressed data part	`{SM}:OS:StartMgr:StartSearch.a,.c`	Ad-hoc
System File, Enabler File	~ 5 sec	Find system file, show Classic Happy Mac, ???????, MacOS screen, ?????????	RAM from System Software files	`{EX}`:{*}	Ad-hoc, MacsBug
High-level MacOS toolbox managers	~ 6 sec	?????????, Progress Thermometer on MacOS screen, ?????????	RAM from System Software files	`{EX}`:{*}	MacsBug
Patches	< 2 sec	MacOS patches are run; this method of fixing bus is no longer necessary because the entire `{SM}` source is built and released with each MacOS now (ROM-in-RAM).	RAM from System Software files	`{EX}:Patches:{*}`	MacsBug
Extensions	~ 10 sec (depends on amount installed)	MacOS Extensions (INITs) are loaded and executed; many show icons for the "Init Parade". This is where a lot of "middleware" starts, such as QuickTime; there is also a large network-related delay here.	RAM from System Software files in Extensions directory; CFM loader	Various groups; see `http://web.apple.com/areas/eng/bbs`.	MacsBug
Finder	~ 6 sec (from launch to finish drawing desktop items)	The Desktop is shown. The Startup app is launched. Often this is only the Finder, however it can include other app in the Startup Items directory and need not include the Finder at all (could be At Ease or any other app).	RAM from applications software; CFM loader, file-mapped loading	Finder group; see `http://web.apple.com/areas/eng/bbs`.	MacsBug, source-level debuggers
Other Apps	Variable	Startup Items are launched.	RAM from applications software; CFM loader, file-mapped loading	3rd-Party	MacsBug, source-level debuggers

G.7. NVRAM

NVRAM (Non-Volatile RAM) holds settings that cannot be on mass storage disks but must still survive power cycles, including both OF settings such as the preferred boot device and OS settings such as the time zone and preferred display resolution.

Historically, NVRAM evolved from PRAM (Parameter RAM). The first Macintosh computers contained only a few bytes of PRAM, often as part of the real time clock (RTC) date/time device. Over time, the RTC devices were able to contain more bytes for more parameters. With the introduction of portables (PowerBooks), the PGE microcontroller, which runs even if the main system power is off, took on the task of containing PRAM; for non-portables, the CUDA microcontroller performs a similar task (in addition to PRAM, PGE and CUDA handle ADB I/O, I2C I/O, Infrared I/O, power up/down/sleep/wake management, real time clock, and more).

Starting around 1995, the PRAM data began to be stored on a separate device: simply an 8K or larger 8-bit wide low power static RAM (SRAM). With the introduction of OF and the CHRP architecture, which are designed to possibly boot multiple OS's, the concept of partitions was introduced (to allow each OS entity its own PRAM "world"), and the need for an all-encompassing name for this plus the change in hardware implementation was cause for the term "NVRAM".

Note that many systems that have NVRAM implemented using a SRAM device, such as Yosemite, may nevertheless still have a CUDA for CUDA's other functiones as described above; the CUDA PRAM function is not used in this case.

G.7.1. User-level NVRAM access

G.7.1.1. User-level NVRAM reset

The out-of-reset key sequence CMD-OPT-P-R clears NVRAM contents (internally it invokes the command"reset-nvram"); that is, it restores all its partitions to default values, and reboots.

The code that activates this is in USER-INTERFACE.of:"(E3 E2 13 15)". Because it happens rather late, NVRAM can be so corrupt that a hang is possible before getting to this point. Thus, there are some other ways in which NVRAM can be reset; see the table "Reset-Time Keyboard User Input Options" for more information.

If CMD-OPT-P-R was used, rather than reset-nvram, and if it was typed on an ADB (not USB) keyboard, then on a CUDA-using machine such as Yosemite, the clock will also be reset because the CUDA device on the motherboard itself, with no OF or OS interaction, notices the CMD-OPT-P-R.

G.7.1.2. User-level NVRAM access when in OF User Interface

When in the OF User Interface (CMD-OPT-O-F), it is possible to display NVRAM settings for the OF Partition only.

OF User Interface NVRAM Commands

Command	Example	Description
`printenv`	`printenv`, `printenv boot-command`	Show contents of "`common`" NVRAM partition
`setenv`	`setenv weather sunny`	Set a variable; create new if necessary
`delenv`	`delenv weather`	Delete existing variable
`"nvramrc"`	-	The contents of nvramrc are taken to be OF code text and are executed before the OF probe process (thus also before User Interface)
`nvedit`	CTRL-C exits; CTRL-L displays; CTRL-Q to insert control character; horrible editor	Editor that edits temporary buffer for the nvramrc setting
`nvstore`	`nvstore`	Store temporary buffer into "`nvramrc`" variable
`nvrun`	`nvrun`	Execute nvramrc contents immediately
`"use-nvramrc?"`	`setenv use-nvramrc? true`	Enable nvramrc execution at OF startup
`reset-nvram`	`reset-nvram`	Reset to defaults (all partitions)
`"aapl,pci"`	-	Variable that is set by the OS that contains properties that are stored in certain nodes; used for such things as OS-to-OF driver communication, such as for startup video card settings such as resolution
`print-aapl,pci`	`print-aapl,pci`	Formatted showing of aapl,pci contents

G.7.1.3. User-level access from MacOS (All Partitions)

In addition to changing OS settings that are stored in NVRAM by means of user-level instruments such as the Startup Disk, Monitors & Sound (resolution), Date & Time (time zone), and other Control Panels, the test application "NVRAM Tool" can be used to examine its contents in all partitions directly. This tool is available from Ben Koning or Bob Bradley. ?????????is there a central server for test tools???????????

G.7.2. Programmatic NVRAM access

G.7.2.1. Programmatic NVRAM access from OF (OF Partition Only)

OF programs can modify variables by means of calls such as "$setenv". For more information, see the "NVRAM-CHRP.of" source code. The following are some coding examples:

\ WRITING OF-all, OF:

\ $setenv sets an NVRAM OF ("common") partition variable to

\ the given value, creating a new variable if necessary:

$setenv ( data-addr data-len name-str name-len )

\ Example: " Sunny" " Weather" $setenv

\ READING OF-all, OF:

\ There is no explicit call to read an NVRAM variable;

\ the OF system makes all variables appear in the

\ "/options" node. Example:

" /options" find-package ( F | pkg T ) if

( pkg ) " Weather" rot ( P L pkg )

get-package-property ( T | P L F ) 0= if

( P L ) type \ will show "Sunny"

then

G.7.2.2. Programmatic NVRAM access from MacOS (Historic)

Historically, there is the semi-private API consisting of ReadXPram and WriteXPram. On newer systems with partitioned NVRAM, these calls will only access the OS-releated data toward the end of the "common" partition, so that the OF variables are inaccessible:

??????????buffer, code (below) ?????? what the hell does code mean? where is length/nvaddr?????

READING pre-OF-2, MacOS:

; pascal OSErr ReadXPram (Ptr buffer, long code)

; buffer -> A0, code -> D0, OSErr <- D0

dc.w $A051 ; _ReadXPram

IMPORT_CFM_FUNCTION ReadXPram

Caution! Private API; exercise discretion

WRITING pre-OF-2, MacOS:

; pascal OSErr WriteXPRam (Ptr buffer, long code)

; buffer -> A0, code -> D0, OSErr <- D0

dc.w $A052 ; _WriteXPRam

IMPORT_CFM_FUNCTION WriteXPRam

Caution! Private API; exercise discretion

There are MacOS Expansion Manager APIs which are useful for older machines for which NVRAM exists but was not yet partitioned using the current scheme; this is the case from the first PowerPC-based Macintoshes to the last machine released before the iMac; that is, all OF-2 machines (it is with OF-3 that the partitioned NVRAM scheme was introduced). So, to read and write non-partitioned NVRAM data, use the following calls. On newer systems with partitioned NVRAM, these calls will only access the OS-releated data toward the end of the "common" partition, so that the OF variables are inaccessible:

READING circa-OF-2, MacOS:

move.w #$022E,D0 ; pascal UInt8 ExpMgrReadNVRAMByte (UInt32 long nvaddress )

dc.w $AAF3 ; _ExpMgrDispatch; note UInt8s are passed as words

IMPORT_CFM_FUNCTION ExpMgrReadNVRAMByte

Caution! Private API; exercise discretion

WRITING circa-OF-2, MacOS:

move.w #$032F,D0 ; pascal void ExpMgrWriteNVRAMByte (UInt32 nvaddress, UInt8 data)

dc.w $AAF3 ; _ExpMgrDispatch; note UInt8s are passed as words

IMPORT_CFM_FUNCTION ExpMgrWriteNVRAMByte

Caution! Private API; exercise discretion

G.7.2.3. Programmatic NVRAM access from MacOS (All Partitions)

MacOS applications do not have to know the format of NVRAM partitions, because MacOS software provides an API for reading and writing NVRAM contents by partition name and index offset within that partition.

There are two APIs to access any part of NVRAM currently. One is the use of RTAS tokens; this is what the NVRAM Tool application does. Note that RTAS may be removed in the future. The other is a couple of MacOS API calls.

MacOS Expansion Manager Private API calls such as "ExpMgrReadNVRAMPartitionByte" can be used to read and write NVRAM data in a partition-aware manner.

READING OF-3, MacOS: ; pascal UInt8 ExpMgrReadNVRAMPartitionByte

move.w #$0530,D0 ; (UInt8 partitionSignature, CStrPtr partitionName, UInt32 nvaddress)

dc.w $AAF3 ; _ExpMgrDispatch; note UInt8s are passed as words

IMPORT_CFM_FUNCTION ExpMgrReadNVRAMPartitionByte

Caution! Private API; exercise discretion

WRITING OF-3, MacOS: ; pascal void ExpMgrWriteNVRAMPartitionByte

; (UInt8 partitionSignature, CStrPtr partitionName,

move.w #$0631,D0 ; UInt32 nvaddress, UInt8 data)

dc.w $AAF3 ; _ExpMgrDispatch; note UInt8s are passed as words

IMPORT_CFM_FUNCTION ExpMgrWriteNVRAMPartitionByte

Caution! Private API; exercise discretion

G.7.2.4. Programmatic raw (non-managed) NVRAM access used internally by BootROM

Since, as mentioned above, various hardware implementations of non-volatile memory are used across different machines, the BootROM must contain different code depending what machine it runs on. In the Hardware Init parts, this is mainly done by conditional compile switches; in the OF parts, this is done by making the non-volatile memory access methods each into an OF device driver, and having the proper driver be opened by machine-specific code (effectively making the "activation" part conditionally compiled).

For a Hardware Init example, Hardware Init code in {BR}:POST:Diagnostics.s calls Write32NV, which is implemented in {BR}:POST:IOControllers.s as per-technology (=per-machine) conditionally-compiled code which knows specifics about talking to various non-volatile memory hardware devices. Keep in mind that this hardware device may well be a microcontroller rather than raw hardware. Hardware Init conditional compile controls are in {BR}:BuildSpecific:Yosemite:Yosemite.s.

For an OF example, the OF code in {BR}:OF:OFSources:Kernel:NVRAM-CHRP.of, which implements high-level NVRAM partition management, calls the low-level raw non-volatile memory access routines as implemented by the OF driver whose ihandle is stored in the OF global "_nvram-ihandle". This variable is initialized (driver opened) during probe time by the machine-specific code in {BR}:OF:OFSources:Projects:Yosemite:THE-TREE.of. These various drivers exist in the {BR}:OF:OFSources:IO directory (for Yosemite, HEATHROW-NVRAM.of, which is FLOADed (source-included) by HEATHROW.of; note that this amounts to conditional compilation across machines). OF conditional compile controls are in {BR}:OF:OFSources:Projects:Yosemite:Yosemite.fth.

For a desktop machine such as Yosemite, the NVRAM hardware is accessed through the Paddington ASIC by simply doing memory-mapped reads or writes to the section of memory (base+0x60000) that it decodes and routes to the 8KByte x 8bit battery-backed up SRAM; see the Paddington ERS for more details. As stated above, this code is in the form of an OF device driver in HEATHROW-NVRAM.of.

Yet for a different desktop machine such as Hemingway/Sawtooth/etc, for which the NVRAM implementation is a partition of the flash BootROM (!) (this saves money; no need for SRAM or battery backup), the code in HEMINGWAY-NVRAM.of thus behaves quite differently (it has hardcoded ROM addresses and knows how to set memory controller bits to enable flash writes) while providing the same OF device drive interface to the high-level NVRAM management code.

G.7.3. Default NVRAM partitions

The partitions that OF-3 currently creates in the routine "INIT-NVRAM" in "NVRAM-CHRP.of" are as follows:

Default NVRAM (Yosemite Example)

Name	Signature	Size (Jan 1999)	Description
`diagnostics`	`0x5f`	`96` (decimal)	Results of various memory tests, if run, are stored here. In the factory, the PowerTest application stores a bitmap of what tests to perform in this partition and then resets the system. The tests are run, results are stored, and they are either disovered by the PowerTest application at the next MacOS boot (if the system comes up) or else this partition can be examined manually at a Rework station. The format of this partition is given in {`BR}:POST:Diagnostics.s`:`"Diagnostic information"`.
`of-config`	`0x50`	`32` (decimal)	"General Purpose OF Partition". Appears to be unused, by BootROM at least, other than its partition being created. There is a comment "By default, if a specified/requested config variable cannot be located in any of the default lists, it will be associated with the "of-config" partition", but there appears to be no code for this?
`of-vpd`	`0x52`	`128` (decimal)	Purpose unknown; meaning of "VPD" unknown. Appears to be unused, by BootROM at least, other than its partition being created.
`common`	`0x70`	`4096` (decimal)	OF settings. They are of the form `name=value\0`.
`POST-err-log`	`0x72`	`80` (decimal)	"POST error log partition". Note that diagnostics results, generated during the running of POST, are stored in its own partition. Perhaps this is for future non-diagnostics POST use. Appears to be unused, by BootROM at least, other than its partition being created. Available by calling the routine "`READ-ERRLOG`".
`APL,MacOS75`	`0xA0`	`1296` (decimal)	MacOS settings; this is what traditional MacOS PRAM access calls will read or write. This partition is created and used by MacOS, not OF. The format is owned by MacOS and defined in SuperMario sources.
`wwwwwww`... (12 bytes of `0x77` ('`w`') signifies free space)	`0x7f`	-	Free space partitions (either "islands" or the bunch of free space at the end) are given a signature of `0x7f`, a name of all `0x77` without the termination `(0x00)` byte, and filled with `0x00`'s.

G.7.4. OF-3 NVRAM Partitioning Format

With the introduction of OF-3, NVRAM contents has followed the CHRP format. NVRAM used to not be divided up into partitions, and so it became inconvenient to maintain a central header file of its format, especially when one considers that a diverse group of OS's, applications, and users want to use it, such as MacOS vs. OF vs. UNIX, System software vs. Factory Diagnostics software, etc. Much better to have individually tagged and checksummed partitions so these different users do not have to share a common include file source base and/or collide.

The format is supposedly governed by a CHRP document, location unknown, but more de facto by code in {BR}:OF:OFSources:Kernel:NVRAM-CHRP.of.

NVRAM space is filled up with a number of partitions. Each partition has a header followed by data, so that consecutively from NVRAM offset zero there exists header, data, header, data, etc. The header contains a name, checksum, etc, and a length for the immediately following partition data. This length is used when walking the partition space while looking for a specific partition in order to access it, delete it, etc.

When a partition is created, if its signature is recognized by the code in NVRAM-CHRP.of as something it knows about, as defined in NVCONFIG-CHRP.def, then after creating that partition it is filled in with default contents.

During probe time, code in NVRAM-CHRP.of - FLOADing (including) - NVCONFIG-CHRP.def calls the routine ADD-DEFAULT to add defaults to the the OF heap, "here" in preparation for adding it to the default list data structures. It is thus in NVCONFIG-CHRP.def where the defaults are found, and there are thus pieces of conditional compile code for various machines there.

When a partition is cleared, it is given a signature of 0x7f and filled with 0x77.

The format of each partition header plus data is as follows:

NVRAM Partition / Header Format

Name	Size	Offset	Format	Description
Signature	1 byte	+`0` (decimal)	Agreed-upon / registered byte value.	Used for finding a partition. Both the Signature and the Name must match.
Checksum	1 byte	+`1` (decimal)	Bytes are added from the Length filed to the end-of-partition-data to an accumulator that starts at `0x00`; if after adding any byte it is equal or greater than `256` decimal, add "`1`" and then `AND` with `0xff`.	Must be valid to find the partition and is updated for delete/create operations at the partition level, but not for data within a partition.
Length	2 bytes	+`2` (decimal)	2-byte word encoded as big-endian, in units of "`1`" = `16`-decimal-bytes of (data plus the header itself).	Used to know partition boundaries.
Name	12 bytes	+`4` (decimal)	12-byte null-terminated string (cstring); "empty" value of all-`0x77` will not have terminator.	Used for finding a partition. Both the Signature and the Name must match.
(payload data)	(variable)	+`16` (decimal)	Managed by owner.	Payload data.

G.7.5. NVRAM Content (OF, OS, Etc)

G.7.5.1. OF Usage of NVRAM

OF NVRAM Content Usage

Name	Default (Yosemite)	Description
`little-endian?`	`false`	If set to `true`, OF runs in little endian mode, such that multiprecision data in memory is stored with least significant byte in lower locations; default is big-endian. See glossary definitions of "big-endian" and "little-endian" elsewhere in this document. However, it is unclear how fully debugged it is; when attempted on Yosemite 1.0 BootROM most OF things worked plus loading the MacOS `'tbxi'` file worked, but then it crashed during `'tbxi'` execution.
`real-mode?`	`false`	If set to `true`, OF runs its own memory world without virtual address translation; that is, at the address given by "`real-base`" (below) instead. Messing this up provides and excellent example of how CMD-OPT-P-R is not sufficient to recover from every case; power-down, AC unplug, battery removal, and CUDA pin 1-39-40 short will be necessary.
`auto-boot?`	`true`	If set to `true`, the command given in "`boot-command`" (see below) is automatically activated; if set to `false`, the User Interface is entered.
`diag-switch?`	`false`	If set to `true`, the OF call "`diagnostic-mode?`" (for which there is a token, so cards can even call it) returns `true`. The idea is for software everywhere to perform self-tests. However, it does not appear to be used by Apple OF; also, there are various individually-enabled debug output facilities for various modules.
`fcode-debug?`	`false`	Does not appear to be used by Apple OF (as of Yosemite 1.0 ship time).
`oem-banner?`	`false`	Setting this to `true` enables "`oem-banner`"; see below.
`oem-logo?`	`false`	Does not appear to be used by Apple OF (as of Yosemite 1.0 ship time).
`use-nvramrc?`	`false`	Enables `nvramrc` (see below) patch facility.
`use-generic?`	`false`	Enables Generic Names, which refers to naming a PCI device which during probe does not have an associated OF ("expansion") ROM from a table built into the BootROM. In this case, the "`name`" property is set using a table lookup in `{BR}:OF:Common:HOST-PCI.of` based on the PCI Class Code. Otherwise (default), the name becomes something of the form "PCIxxxx,xxxx". The latter seems to be required by poorly-behaved MacOS device drivers that look for a specific name to positively identify their device.
`default-mac-address?`	`false`	Does not appear to be used by Apple OF (as of Yosemite 1.0 ship time). Becomes more important for net booting. There is, however, a OF call "`mac-address`" which returns this information. The mac address is the hardware Ethernet ID and has nothing to do with Macintosh.
`real-base`	`-1`	Causes OF to override the setup for its memory world upon its startup right after Hardware Init handoff upon its startup right after Hardware Init handoff. For the settings `real-base`, `real-size`, `load-base`, `virt-base`, and `virt-size`, if they are set to nondefault, the following happens: Use only the high 3 hex digits (`AND` with `0xFFF00000`); else use -1 default or -1 if NVRAM setting not defined. Decide if a reboot is necessary to any of these settings changed since last time or if they are not those that are passed in through the StartVec data structure upon the Hardware Init to OF handoff. Store them all in a structure and pass that structure to the routine " `(RESTART)`" in `KERNEL.fas`, causing restart of OF in the new mode. Unkown if this all really works as of this time (18-May-1999), but it seems a holdover from the CHRP effort and appears to not be a current requirement.
`real-size`	`-1`	Causes OF to override the setup for the size of its memory world upon its startup right after Hardware Init handoff; the default of `-1` causes it internally to be set to `0x200000` (2 MB). See also `real-base`.
`load-base`	`0x800000`	Causes OF to override the setup for the global variable "`load_base`", the virtual address of where the '`tbxi`' file secondary OS loader is loaded, upon its startup right after Hardware Init handoff. See also `real-base`.
`virt-base`	`-1`	Causes OF to override the setup for its memory world upon its startup right after Hardware Init handoff. These are the addresses usually seen when manipulating variables, constants, etc, in OF; the default of `-1` causes it internally to be set to `0xff800000`. See also `real-base`.
`virt-size`	`-1`	Causes OF to override the setup for the size of its memory world upon its startup right after Hardware Init handoff; the default of `-1` causes it internally to be set to `0x200000` (2 MB). See also `real-base`.
`pci-probe-mask`	`-1 (all 1's = all enabled)`	Bitmap of PCI devices to skip during OF Probe. Setting bits to zero disables. Motherboard devices above and below the motherboard PCI-PCI Bridge and the Slots all fit in the same bit map.
`screen-#columns`	`100`	Does not appear to be used by Apple OF (as of Yosemite 1.0 ship time).
`screen-#rows`	`40`	Sets the number of lines before the "`More [<space>,<cr>,q] ?`" message appears when most words that produce user interface output are operating, such as "`ls`", etc.
`selftest-#megs`	`0`	Does not appear to be used by Apple OF (as of Yosemite 1.0 ship time).
`boot-device`	`hd:,\\:tbxi`	First-try OF mass storage path to secondary loader (OS) file that Mac-Boot attempts to load and run. This variable is set by the MacOS Startup Disk Control Panel. The Control Panel will usually set a specific drive ID, partition, etc; the factory default shown here uses the "`HD`" alias to point to the "main" drive and omits the partition number so that a search for the first MacOS partition occurs.
`boot-file`	(none)	Unused by OF, but some OS secondary loader programs (UNIX) may write into this variable for later use.
`boot-screen`	(none)	Does not appear to be used by Apple OF (as of Yosemite 1.0 ship time).
`console-screen`	(none)	Does not appear to be used by Apple OF (as of Yosemite 1.0 ship time).
`diag-device`	`floppy`	Does not appear to be used by Apple OF (as of Yosemite 1.0 ship time).
`diag-file`	`diags`	Does not appear to be used by Apple OF (as of Yosemite 1.0 ship time).
`input-device`	`keyboard`	Allows for at-reset-time redirection of input to something other than the built-in devices ("console"), such as a serial port. Try typing "`scca io`" on Yosemite with a 57600/8/N/1 terminal connected an adapter card in the Modem slot.
`output-device`	`screen`	See about, but for substituting an output device instead of the found-video card (Yosemite) or onboard video.
`mouse-device`	`mouse`	Does not appear to be used by Apple OF (as of Yosemite 1.0 ship time).
`oem-banner`	(none)	String to print out upon entering OF User Interface; see also "`oem-banner?`" above.
`oem-logo`	(none)	Does not appear to be used by Apple OF (as of Yosemite 1.0 ship time).
`nvramrc`	(none)	OF code text that is run before the probe and user interface init; can be used for "patching". See "`use-nvramrc?`" (above).
`boot-command`	`mac-boot`	OF command to execute after OF is up (probe and basic I/O device init (keyboard, screen, etc) complete). Mac-Boot is the boot search code, which uses the `boot-device` setting (above).
`forced-boot`	(none)	Automatically execute the given string after entering the User Interface; it thus gets displayed and the console is up, thus text output is visisble. It only has effect for one boot (it is cleared when it runs); entering with CMD-OPT-O-F clears it also.
`fw-scsicfg`	(none)	Does not appear to be used by Apple OF (as of Yosemite 1.0 ship time).
`fw-boot-path`	(none)	Does not appear to be used by Apple OF (as of Yosemite 1.0 ship time).
`default-client-ip`	(none)	Used as addressing information when using the Ethernet driver if no address is given on the pathname syntax that specifies a `BOOTP` request.
`default-server-ip`	(none)	Used as addressing information when using the Ethernet driver if no address is given on the pathname syntax that specifies a `BOOTP` request.
`default-gateway-ip`	(none)	Used as addressing information when using the Ethernet driver if no address is given on the pathname syntax that specifies a `BOOTP` request.
`default-subnet-mask`	(none)	Does not appear to be used by Apple OF (as of Yosemite 1.0 ship time). Becomes more important for net booting.
`default-router-ip`	(none)	Does not appear to be used by Apple OF (as of Yosemite 1.0 ship time). Becomes more important for net booting.
`boot-script`	(none)	Does not appear to be used by Apple OF (as of Yosemite 1.0 ship time). Not to be confused with the boot script that is the format of the `'tbxi'` file that is processed by `BOOTINFO-LOADER.of`.
`aapl,pci`	(none)	Set by OS, ie MacOS, and executed to create properties.
`ASVP`	`01060;001400` (example)	Set by video card or macos?????????

G.7.5.2. OS Usage of NVRAM for Parameters

refer to other document or say that OS can use nvram to store things

G.7.5.3. OS Usage of NVRAM for Patching

describe how the OS can put patches in nvramrc for fixing OF bugs

G.7.5.4. OS Usage of NVRAM for Setting of OF Behaviors

describe how AAPL,PCI nvram setting works

G.8. Out-Of-Reset keys

In addition to entering the OF user interface, the following is a complete description of all currently known the things a user can do to affect what happens at reset time for all software parts of the system.

Reset-Time Keyboard User Input Options

Action	Activation Method	Feedback	Who Does It	Mode Entered
Normal boot	Nothing	Boot Beep	Hardware Init runs its reset vector in `BootBlock.s`, does RAM sizing and much other hardware init in `HardwareInit.s`, uncompresses OF, runs OF; OF initializes its kernel; OF does its probe; OF does its runtime stuff, such as Multiboot, and the OS secondary loader (`'tbxi'` file) gets loaded and executed.	OS (or OF if `auto-boot?` set to `false`)
Multiboot	Option out of reset	Screen and mouse	OS Picker code part of `MULTI-BOOT.of`.	GUI OS Picker in OF
Reset NVRAM (not bulletproof)	Command-Option-P-R out of reset (mnemonic "Parameter Ram")	Keeps boot beeping every few seconds until keys released	OF detects this key sequence and resets NVRAM. This happens late enough that severely corrupted NVRAM contents can hang OF, so see also below.	Normal boot with NVRAM parameters reset to factory defaults
OF	Command-Option-O-F out of reset (mnemonic "Open Firmware")	White command line screen, or serial I/O	`USER-INTERFACE.of` and many other files are involved in presenting a programming environment; see References section.	OF User Interface
Run with default NVRAM settings	From power up: NMI button down > 5 sec, and hold after simple beep, while giving no serial input	Simple Beep (not boot beep)	Normal boot after the simple beep, but with a default set of "NVRAM" OF settings, which are hardcoded and do not come from NVRAM at all; indeed, NVRAM contents are left alone. It may be desirable to enter OF and execute the "`reset-nvram`" command.	Normal boot as far as OF is concerned; OS may have trouble
Reset NVRAM (absolute last resort)	Disconnect AC plug (trickle power); remove battery (backup); leave for hours or short U40 (CUDA) pins 1, 39, 40 for several seconds (bulk capacitance)	None	You do. It is necessary to cause the NVRAM contents stored in U19 (SRAM) to be lost, and there are several ways that power keeps going to that device.	Normal boot with NVRAM parameters reset to factory defaults
Boot ROM Flash Update Enable	From power up only: NMI button down > 5 sec, then release after simple beep	Simple Beep (not boot beep)	Hardware Init, in `BootBlock.s`.	Normal boot with the Boot ROM write-enabled for flash updating
MiniNub debugger	From power up: NMI button down > 5 sec + serial port input (ie, pressing RETURN on terminal)	Serial port output (57600/8/N/1)	Hardware Init, in `BootBlock.s` and `MiniNub.s`.	MiniNub, before most of Hardware Init; "`x`" continues, "`?`" gets help
Serial Test Manager (EMMO / STM)	Same as MiniNub but with EMMO signal asserted	Same as MiniNub	Same as MiniNub.	MiniNub with extra commands
Snag Boot CD	From reset: "C" key down	CD activity	Boot Search, in `Multiboot.of`.	Attempt to boot from CD before any other boot device search
Snag Boot HD	From reset: "D" key down	Nothing special	Boot Search, in `Multiboot.of`.	Attempt to boot from "main" hard drive before any other boot device search
Snag Boot Network	From reset: "N" key down	Slower	Boot Search, in `Multiboot.of`.	Attempt to boot from network (do local `BOOTP` request) before any other boot device search
Snag Boot Override	From reset: Command-Option-Shift-Delete ("CSOD", pronounced "see-sod")	Various	Boot Search, in `Multiboot.of`.	Attempt to boot from a device other than the one selected in the OS Control Panel / NVRAM `boot-device`
Eject Removable Device (non-CD)	From reset: Mouse Button down	ZIP eject	Boot Search, in `Multiboot.of`.	Attempt to eject ZIP disk (for Yosemite), then normal boot
Boot Search Caution	None	Blinking Happy Mac / Question Folder	If `Multiboot.of`, using `BootPath-Search.of` cannot immediately find a boot volume, and has to resort to a search of all devices (perhaps including plug-in PCI cards), it displays a blinking folder	Normal boot when a boot volume found
OS (MacsBug) debugger	Control key down out of reset; Control-Power at any time	MacsBug	OS level debugger, after OS secondary loader but early on in OS boot	MacsBug, in early stage of MacOS boot; "`g`" continues, "`?`" gets help
Extensions off	Shift key down out of reset	"`Extensions Off`"	OS tertiary loader; ie, code in "`System`" or "`Enabler`" file	OS without Extensions "middleware"
Rebuild Finder desktop database	Command-Option down out of reset	Confirmation dialog	Finder (OS program selector; the first application program to run) after OS is fully loaded	Finder icon database reset

G.9. Debugging

G.9.1. Overview

A handful of debugging facilties exist. In addition to an interactive tracer, most of these finction by outputting text progress of some kind. Note that some are activated by means of a compile time switch, necessitating rebuilding, while others have runtime switches which take up more code space but are available anytime, even in shipping machines.

Text I/O can happen over the serial port or console (keyboard and video driver). However, some of the more primitive output facilities, such as the MiniNub and the Logger, work over the serial port only.

G.9.2. Serial Test Manager (STM)

The Serial Test Manager is required for manufacturing diagnostics. Since manufacturing is critically process-oriented, software interactions are simple, precisely defined, and may not change arbitrarily.

The Serial Test Manager commands, used during manufacturing assembly line testing, are implemented as extra MiniNub (see below) commands and by virtue of MiniNub outputting a different prompt (the STM prompt). This feature of the MiniNub is enabled only if STM is enabled; this in turn is done by Hardware Init if it discovers that the EMMO bit in the Apple Paddington ASIC is set. This bit is set if the board is installed in the EMMO test fixture. See table of MiniNub commands below.

G.9.3. MiniNub

A very primitive, pre-Hardware Init debugger, which works over the serial port only, and has an absolute bare minimum of commands, is available with the key sequence

NMI button down at power-up + serial port input activity

(note that this is similar to the NMI button being down for more than 5 (kMininubWaitSeconds) seconds at power-up to enable Boot ROM flashing (see table); note further that it is the Apple Paddington ASIC's "interrupt levels" register that allows reading of the state of the NMI button).

G.9.3.1. MiniNub commands

The MiniNub is fully documented elsewhere, but in summary it has the following commands:

MiniNub Commands

MiniNub Command	Action
`?`	Help menu
`x`	Exit (`rfi` return from interrupt, perhaps to continue booting)
`td`	Display all registers ("Dumpster")
`dm addr len` `db addr` `dw addr` `dl addr` `sb addr val` `sw addr val` `sl addr val`	Display (dx) or set (sx) memory range (xm) or byte (xb), word (xw), or long (xl). Bytes are 8-bits, words are 16-bits, and longs are 32-bits; they are printed and expected in little-endian format (least significant bytes are stored in earlier memory addresses)
`dmn addr len` `dbn addr` `dwn addr` `dln addr` `sbn addr val` `swn addr val` `sln addr val`	Like memory display and set commands above, but regarding NVRAM space
`dlc addr` `slc addr val`	Like memory display and set commands above, but regarding PCI Bus Config Space cycles
`mcio` `grkl`	Display mac-io (ie, Paddington) or Grackle (MPC106 memory and PCIcontroller) - specific registers
`t0 - ROM Checksum` `t1 - Address Line` `t2 - Data Line` `t3 - Memory Simple` `t4 - Mod 3 Forward` `t5 - Mod 3 Reverse` `t6 - NVRAM` `t7 - L2 Cache` `t8 - Address Pattern` `t9 - NTA Word` `tb - Memory Quick` `a - All` `q - Quick`	These are STM (Serial Test Manager) commands used by EMMO (Enhanced Mac Minus One) logic board breakout bed of nails vacuum fixture test used in the factory. They are available only if the EMMO signal input to the Paddington ASIC has been asserted by the text fixture. If the test fails, expected EMMO failure report format is as follows: "`=F=T<Test No>=<Good Data>=<Bad Data>=<Failing Address>=<Failing Bank>=<Test Results><cr><lf>`"; note that "=" acts a delimiter between the data being sent.
(Other commands)	There are various other commands but they may not be fully implemented or work in all situations.

G.9.4. Browsing

It is beyond the scope of this document to discuss the OF User Interface as might be used for browsing and debugging; nevertheless, we include a few very common commands here:

Command	Description
`see ( "word<cr>" -- )`	Disassembles the given word name (usually a "routine", but could be a variable, contant, etc; they are much the same thing in Forth), searching the "current vocabulary" (the current node in `dev`/`pwd` browsing, that is, the current `active-package` setting) first, and then then OF "System" calls.
`xsee ( xt -- )`	Headers must be enabled for this (conditional compile flag `IGNORE-HEADERLESS`). Displays a word as hex data (FCODEs, etc) alongside their text disassembly.
`(see) ( xt -- )`	Same as `see`, but takes as input an execution token number instead of a word name.
`(xsee) ( xt -- )`	Same as `xsee`, but takes as input an execution token number instead of a word name.
`dis ( ptr -- )`	Displays 32bit hex quantities starting at the given address.
`debug ( "word<cr>" -- )`	The next time `word` is executed, a debugger is invoked, whose commands are, but not limited to, `space-bar`=step-over, `d`=step-into, `g`=go, `q`=abort.
`dump ( ptr len -- )`	Print the given number of bytes as hex and ascii, with addresses.
`dumpl ( ptr len -- )`	Same as `dump` but displays as little-endian 32-bit longs.
`.cregs ( cptr -- )`	Print the first 0x40 bytes of PCI config space registers, given a config space address. For example: "`dev usb .properties` (note the "13000" reg entry) `13000 .cregs`". For debugging a PCI device's PCI bus setup.
`do-config-l@ ( cptr -- )`	Do a PCI config space read cycle to the given PCI config space address (see `.cregs` above). For debugging a PCI device's PCI bus setup.
`do-config-l! ( value cptr -- )`	Do a PCI config space write cycle to the given PCI config space address (see `.cregs` above). For debugging a PCI device's PCI bus setup.
`do-map ( phys virt size mode -- )`	Alter CPU's memory mapping; can be used to manually cause an address range to be accessible. For example, to look at the raw Boot ROM contents: "`fff0000 300 dump` (note the crash) `fff00000 fff00000 100000 28 do-map fff0000 300 dump`".
`create playmem 4000 allot playmem 4000 99 fill " hd:,\\:tbxi" open-dev value ih 0 0 " seek" ih $call-method u. playmem 333 " read" ih $call-method u. playmem 333 dump`	This is an example of how to dump the contents of a file.

G.9.5. Text Output

Often the easiest way to debug something is to print messages during runtime. While this often requires recompilation, it can still be faster than debugging after the fact, and in some cases, it may be the only way to debug due to debugger interaction, debugger nonavailability, or speed- or sequence- sensitive sections.

G.9.5.1. Normal (Post-User Interface) OF debug output

dddddddddddddddddddddddddddddddddddd

G.9.5.2. Pre-User-Interface Text Output

Text that is output in the OF world at probe-time, that is, before the User Interface is entered, is stored in memory for dump. If you enter the OF User Interface and you see text output before the "Welcome to Open Firmware" banner greeting, that text was due to emit, type, etc, calls that happened before the UI was up.

Caution -- When debugging in this situation, it is important to keep in mind that 1) you are not seeing the text output as it is happening, so the timing is irrelevant (the order is ok, however), and 2) if you crash/hang, you will not ever see any output, even output caused by "good" code beyond the crash/hang point, so you cannot find out "where" you crashed, only "that" you crashed.

There is a maximum size of 25% of total free OF memory for the text queue; data is lost off the top so the most-recent 25% would be available.

G.9.5.3. Global Text Output (Instrumentation) Services

Global Debug Text Output Facilities

Area	Activation Method	Enabled At	Description
Hardware Init	Equate in `BuildSpecific:Yosemite.s` called "`Debugging`"	Compile time	This is not used by any of the Hardware Init source files in the `POST` directory that Yosemite uses; several other projects do use it, however
Logger	"`WITH-LOGGER`" conditional compile constant existence in, ie, `Yosemite.fth;` wherever source code uses `logger`, `logger-u.`, `logger-type`, etc, for output	Compile time	Allows debugging during OF probe time (before the User Interface comes up) over serial port A at 57600/8/N/1; if the logger is called after the console I/O services are already up then those are used instead
Logger over I²C bus	"`I2C-LOGGER`" conditional compile constant existence in, ie, `Sawtooth.fth`	Compile time	For machines without a serial port, logger information can also travel over the I²C bus
Time-Stamp	Same as Logger; wherever source code uses `time-stamp` (many places), logger output is produced	Compile time	Logger output is produced showing many stages of pre-console and pre-user-interface execution, including probe time; invaluable for debugging
Time-Stamps Array	Always active; wherever source code uses `time-stamp`, time stamp data is filled in array	Compile time	The OF global "`time-stamps`" points to memory that is filled with ms timer and stack depth values encountered whenever `time-stamp` was called; a word to dump the time-stamps will appear soon
Headers (OF "Symbols")	"`IGNORE-HEADERLESS`" conditional compile constant existence in, ie, `Yosemite.fth`	Compile time	Invaluable for debugging; everything is listed when using "words" or using "see" in the User Interface, regardless of `HEADERLESS` / `EXTERNAL` directives in code
MacOS ROM / `tbxi` file	`AAPL,debug` property existence in the "`/`" root node; 32-bit value is a bitmask of how much to output. For example: "`dev / -1 encode-int " AAPL,debug" property`"	Runtime	Dumps out a huge amount of text during "trampoline code" execution; that is, the first native machine code that runs after handoff from OF which setups up data for MacOS using Client Interface callbacks to OF

G.9.5.4. Localized or Specialized text output

Specialized Debug Text Output Facilities

Area	Activation Method	Enabled At	Description
HW Init / Logic Analyzer	Equate in BuildSpecific:Yosemite.s: `DebugWriteAddr`	Compile time	Address for logic analyzer to trigger on during bring up develoment
RTAS	Add "`-D DEBUG`" setting in `RTASDEFINES` in `Yosemite.make`	Compile time	Some debug printouts when an RTAS routine is called through the Client Interface; however, for some of the debug outputs, "`printf`" is used, so I don't see how it could work since no kind of stdio is linked
BootPath-Search	NVRAM variable existence: `aapl,debug-bps`. This used to be the`AAPL,debug-bootpathsearch`property existence in the "`/`" root node	Runtime	Text output of all BPS API calls (coming from Multiboot) and some internals
Multiboot	NVRAM variable existence: `aapl,debug-mb`. This used to be the`AAPL,debug-bootpathsearch`property existence in the "`/`" root node	Runtime	Text output of state of Multiboot (executive boot search algorithm and OS Picker)
Ethernet driver	Debugging routine `.enet-state`when in operating Ethernet driver node (except may be conditionally compiled out of `BMAC.of` or `DEC21140.of` )	Runtime (except see previous column)	Print out lots of registers and driver state variables
Firewire driver	`DEBUG-FLAGS` in `FIREWIRE-LYNX.of`	Compile time	Packet and debug info
USB driver	Creating `DEBUG-USB` variable existence in `Yosemite.fth`.	Compile time	Debug info; additionally, the value affects how much is output; see `USB-OPENHCI.of`; bit vector of:`fShowSetup=0x1, fShowDone=0x2,fShowBulk=0x4,fShowAllocFree=0x8,fShowProbe=0x10`
Client Interface	`ciDebug?` variable in `CI-WORDS.of`	Compile time	Watch Client Interface API calls go by
NVRAM driver and format controller	`NVRAM-DEBUG?` variable in `NVRAM-CHRP.of`	Compile time	Internal debug info; ie, invalid format flagging
Makefile(s)	Option "`-debug`" on BBS command line; ie: `bbsbuild BootROM Yosemite -debug`	BBS time (before compile)	For debugging build scripts
Makefile(s)	Option "`-echo`" on BBS command line; ie: `bbsbuild BootROM Yosemite -echo`	BBS time (before compile)	For debugging build scripts
Somewhat obsolete global debug build setting	Creating `DEBUG-BUILD` variable existence in `Yosemite.fth`; additional module-specific variables may need to be set, ie, `SCSI-T-DEBUG?` in `SCSI-Tape/Disk.of`.	Compile time	Older method for causing debug output; still used in only one module: MESH Narrow SCSI driver
ELF Loader	Creating `ELF-DEBUG` variable existence in `Yosemite.fth`	Compile time	Debug ELF loader (Extended Load Format)? Not used very much.
PCI Probe Mask	NVRAM setting `pci-probe-mask;`bitfield of PCI devices to skip during probe bit position corresponds to PCI device number; "`0`" means do not probe; default setting `0xffffffff` (all enabled)	Runtime	Allows shut-off of probing for selected PCI devices (thus both motherboard and slot); bit number corresponds to PCI device ID; for Yosemite it covers both MPC 106 and DEC bridge

G.9.5.5. Client Interface debug output

xxxxx programs can make CI callbacks; talk about stdio lib that does this

G.9.5.6. Text output supression

G.9.5.6.1. Text output by OF "system" code in general

Many pieces of code in OF, especially device drivers, output text error messages if things go wrong (in some cases, even if things are successful). Since this is not desired for programmatic things such as the boot search algorithm (which must make many ill-fated driver calls), various mechanisms exist for suppression of output. BootPath-Search, for example, used to temporarily point the emit and type defer word vectors to a dummy, before making use of the

ignore-output?

facility. Ignore-output? is a global OF variable that, when set to true, causes text output to be suppressed. BootPath-Search debug output is unaffected by this internal working. Currently, Multiboot also uses it, though in a more global way; this is because the OF "system" services that it calls (ie, $boot, etc) do not themselves normally suppress their error text output (nor should they in the current scheme). Multiboot could perhaps be revved to contain output-supressing wrappers for all relevant calls.

G.9.5.6.2. xxxxxxscca" or "`screen`" devalias
The `RESOLVE.of:INSTALL-CONSOLE` routine calls the `RESOLVE.of:OUTPUT` routine with the rhs setting of NVRAM " `output-device`" lhs

The `RESOLVE.of:OUTPUT` routine tries to `OPEN-DEV` the new output device; if succeed, put the ihandle into the "`stdout`" variable and close the old one; if fail, nothing changes

Note that `INSTALL-SCREEN`, which tries to open-dev the "`screen`" alias explicitly and sets the global `_SCREEN-IHANDLE`, is not used by the OF user interface by default but is used by Mac-Boot, because Mac-Boot implements a graphical interface (and indeed, for debugging, the serial port node "`scca`" can be used as the OF user interface console while it does graphics on a graphics node "`screen`").

The screen device that is opened will be the last one whose phandle was stored in the `_DISPLAY` global; see `HOST-PCI.of` and `RESOLVE.of`'s `SearchForDisplay` and `?has-display` routines.

????is the above all correct????

G.4.4. OF User Program Execution

user interface or not, then NVRAM boot-command or mac-boot

usually from here on we do mac-boot / multi-boot, which searched for an OS to boot

G.5. Mass Storage

G.5.1. file I/O standard features

G.5.3. Mass storage pathname syntax

OF (starting with OF-3) supports the mass storage pathname syntax as described in the IEEE and Firmworks documentation:

Mass Storage Syntax

File Pathname= [driver-spec][device-spec][volume-spec][file-spec]

driver-spec is the path to a device driver, that is a node of device_type "block"

driver-spec = [devalias[/further/qualified] | [/full/path/starting/with/slash]

device-spec is the ID of the targeted drive on the bus, ie, a SCSI ID, or 0/1 for Master/Slave

device-spec = [@id-in-hex]

volume-spec is the location of the desired data partition within the drive

volume-spec = [,lun-in-hex][:[partition-in-decimal]]

· Partition numbers are on-disk partition numbers, usually the first MacOS partition is on 4 or 5.

· Specifying a 0 for the partition number causes no partitioning interpretation to take place; use this to access raw data from the beginning of the disk or lun.

· Not specifying a partition number (but the comma must be included) causes a search for the first acceptable partition to take place.

file-spec is the location of the file on the file system volume

file-spec = [,path-start[path-to-file] | [:type]]

· path-start = \ | \\A single backslash means from root of file system, a double backslash means from the System Folder directory

· path-to-file = pathname-components\with\backslashes\for\directories

· pathname-components can have "%xx" for special character escape, where "xx" is a two-character hex ASCII value. UniCode values may also be specified as "%xxxx".

· type is a 4-character MacOS filetype to search for.

Notes:

The device id is given in hex, the lun is given in hex, but the partition is given in decimal.
See below for search policies for finding partitions and file systems.

The partition is accessed by using the OF partition number given, multiplying by 0x200, and interpreting the data as a Macintosh partition map entry as defined in Inside Macintosh: Devices: 3-25.
The partition must be "valid". "Valid" means: The partition map entry block's signature "pmSig" field (+0 decimal offset) must be "PM" (0x504d 16-bit big-endian) and the partition type "pmPartType" field (+48 decimal offset) must start with the case-sensitive characters "Apple_HFS" or "Apple_Boot" (that is, Apple_HFS*|Apple_Boot* is matched).

A search is done by walking the various partition map entries from the beginning of the disk; the first "valid" partition, as specified above, wins.
This search is started by reading 0x200 bytes starting at 0x200 from the beginning of the disk (that is, one "block" starting at "block" 1 (regardless of the actual device driver block size, partition format "blocks" are apparently always 0x200 bytes long)). This block's "pmMapBlkCnt" field (+4 decimal offset) is interpreted at a 32-bit big-endian number indicating the number of partitions to search.